📝 Overview

VoidSpawn is a high-performance Paper/Spigot plugin designed to automatically teleport players to safety when they fall into the void. The plugin monitors each player's Y-coordinate and instantly teleports them to a designated spawn point when they fall below a configurable threshold.

How It Works

1. Players fall below the configured Y-level threshold for their world
2. The plugin instantly detects the void fall
3. Players are teleported to a custom spawn point (set via /vs setspawn)
4. If no custom spawn exists, players are sent to the world's default spawn
5. A smooth fade animation and sound effect enhance the experience

✨ Key Features

🎯 Core Functionality

• Multi-World Support - Configure unique Y-levels for each world
• Custom Spawn Points - Set specific teleport locations with exact orientation
• Default Spawn Fallback - Automatic fallback to world spawn if custom spawn not set
• Optimized Detection - Lag-free performance even with many players

🎨 Player Experience

• Smooth Fade Effect - 2-second fade-in/fade-out screen transition
• Customizable Messages - Full color code support with & formatting
• Sound Effects - Configurable teleport sounds
• Cooldown System - Prevents teleport spam and exploitation

🛡️ Administration

• Permission-Based Access - Granular control over commands and bypass
• Hot Reload - Update configuration without server restart
• Per-World Configuration - Enable/disable void protection per world
• Minecraft 1.20+ - Full compatibility with latest versions

🚀 Installation

Requirements

• Minecraft Server: Paper/Spigot/folia 1.20 or newer
• Java: 17 or higher

Setup Steps

1. Download VoidSpawn-1.0.0.jar
2. Place the file in your server's plugins/ folder
3. Restart your server
4. Configure the plugin (files created automatically):
   • plugins/VoidSpawn/config.yml
   • plugins/VoidSpawn/spawns.yml

🎮 Commands

Administrator Commands

Alias: /voidspawn works identically to /vs

🔐 Permissions

⚙️ Configuration

config.yml Structure

# Fade Effect Settings
fade-effect-enabled: true  # Enable/disable screen fade animation

# Sound Settings
teleport-sound: ENTITY_ENDERMAN_TELEPORT  # Sound played on teleport (use 'none' to disable)

# Cooldown Settings
teleport-cooldown: 3  # Seconds before player can be teleported again

# Messages (supports & color codes)
teleport-message: "&aYou have been teleported to safety!"
spawn-not-set-message: "&eNo custom spawn set. Teleporting to world spawn..."
cooldown-message: "&cPlease wait before being teleported again."

# World-Specific Settings
worlds:
  world:
    y-level: -64      # Players below this Y-level are teleported
    enabled: true     # Enable/disable void protection for this world
  world_nether:
    y-level: -64
    enabled: true
  world_the_end:
    y-level: -64
    enabled: true

Configuration Options

Visual Effects

• fade-effect-enabled: true/false
  • Enables smooth screen fade during teleportation
  • Duration: 2 seconds total (1s fade out, 1s fade in)

Audio Settings

• teleport-sound: Sound name or none
  • Default: ENTITY_ENDERMAN_TELEPORT
  • Must be valid Bukkit Sound enum name
  • Set to none to disable sound

Anti-Spam Protection

• teleport-cooldown: Integer (seconds)
  • Prevents repeated rapid teleportations
  • Default: 3 seconds
  • Helpful for preventing abuse

World Configuration

For each world, configure:

• y-level: Y-coordinate threshold (players below this are teleported)
• enabled: true/false to toggle void protection

🗺️ Setting Up Spawn Points

Initial Setup (Required)

1. Ensure you have OP status or voidspawn.admin permission
2. Enter the world you want to configure
3. Stand at the exact location where players should spawn
4. Face the direction players should be facing
5. Execute: /vs setspawn
6. Confirmation message will appear

What Gets Saved?

• World name
• X, Y, Z coordinates
• Yaw (horizontal rotation)
• Pitch (vertical rotation)

Without Custom Spawn

If no custom spawn is set via /vs setspawn, players will:

1. Receive the spawn-not-set-message
2. Be teleported to the world's default spawn point
3. Still benefit from void protection

🔧 Advanced Usage

Multiple Worlds

Configure different Y-levels for each world type:

worlds:
  survival_world:
    y-level: -64
    enabled: true
  creative_world:
    y-level: -128
    enabled: false  # Disable in creative
  mining_world:
    y-level: -64
    enabled: true

Custom Messages

Use Minecraft color codes with &:

teleport-message: "&b&lVOID RESCUE &r&7» &aYou've been saved!"
spawn-not-set-message: "&e&l⚠ &7Using default spawn point..."
cooldown-message: "&c&l✖ &7Wait {cooldown}s before next teleport"

Performance Tuning

The plugin is optimized by default, but you can:

• Disable fade effects for minimal overhead
• Adjust cooldowns to reduce event frequency
• Disable in creative/spectator worlds

📊 Performance Information

VoidSpawn is built with performance as a priority:

• Optimized Event Handling: Only processes relevant player movement events
• Memory Efficient: Automatic cleanup on player disconnect
• No Tick Lag: Asynchronous processing where possible
• Minimal Overhead: Typically <1% CPU usage even with 100+ players

Best Practices

• Set appropriate Y-levels (don't set too high)
• Use reasonable cooldowns (3-5 seconds recommended)
• Disable in worlds where void protection isn't needed

❓ Troubleshooting

Players aren't being teleported

• Check if void protection is enabled for that world in config.yml
• Verify the Y-level is set correctly
• Ensure players don't have voidspawn.bypass permission
• Check server console for errors

Spawn point not working

• Confirm spawn was set with /vs setspawn
• Check spawns.yml for the world entry
• Try setting the spawn again
• Verify world name matches exactly

Performance issues

• Disable fade effects if experiencing lag
• Increase cooldown duration
• Check for conflicting plugins
• Review server TPS with /tps command

📞 Support

For bug reports, feature requests, or general support, please contact the development team.