# FirstJoinTeleport<\/p>\n
FirstJoinTeleport is a lightweight Paper plugin that automatically teleports players to random safe locations within a configurable area when they first join a specific world. Perfect for survival servers where you want players to start in random locations rather than at spawn.<\/p>\n
## Features<\/p>\n
– **Automatic Teleportation**: Players are automatically teleported when entering a configured world
\n– **One-Time Teleportation**: Each player is only teleported once per world (prevents repeated teleports)
\n– **Configurable Area**: Define a square radius where players can be teleported
\n– **Countdown Timer**: Configurable countdown before teleportation (default 3 seconds)
\n– **Safe Location Finding**: Automatically finds safe locations with infinite retries
\n– **Performance Optimized**: Uses async chunk loading to prevent server lag
\n– **Customizable Messages**: Fully customizable messages (defaults in Spanish)
\n– **Data Persistence**: Player teleportation status is saved automatically
\n– **Safety Checks**: Avoids water, lava, void, and cave locations (minimum Y=60)<\/p>\n
## Requirements<\/p>\n
– **Server Software**: Paper or Spigot 1.20 or higher
\n– **Java Version**: Java 21 or higher<\/p>\n
## Installation<\/p>\n
1. Download the latest JAR file from Modrinth
\n2. Place the JAR file in your server’s `plugins` folder
\n3. Restart your server or use `\/reload`
\n4. The plugin will automatically create a `config.yml` file in `plugins\/randomteleport\/`<\/p>\n
## Configuration<\/p>\n
The configuration file is located at `plugins\/randomteleport\/config.yml`. After making changes, reload the plugin or restart the server.<\/p>\n
### Configuration Options<\/p>\n
#### `target-world` (default: `”world”`)<\/p>\n
The name of the world where teleportation should occur. Players entering this world will be teleported (if they haven’t been teleported before).<\/p>\n
“`yaml
\ntarget-world: “world”
\n“`<\/p>\n
#### `radius` (default: -1000 to 1000)<\/p>\n
Defines the square area where players can be teleported. Coordinates are relative to the world’s spawn location.<\/p>\n
“`yaml
\nradius:
\n min-x: -1000
\n max-x: 1000
\n min-z: -1000
\n max-z: 1000
\n“`<\/p>\n
**Example**: With spawn at (0, 64, 0), `min-x: -1000, max-x: 1000` creates a 2000×2000 block area centered at spawn.<\/p>\n
#### `countdown-seconds` (default: `3`)<\/p>\n
Duration of the countdown before teleportation in seconds. Players see countdown messages during this time.<\/p>\n
“`yaml
\ncountdown-seconds: 3
\n“`<\/p>\n
**Note**: Setting this to 0 will teleport immediately (not recommended as players won’t see any warning).<\/p>\n
#### `messages` (all configurable)<\/p>\n
All messages support Minecraft color codes using the `&` symbol. The placeholder `{seconds}` is replaced with the countdown number.<\/p>\n
“`yaml
\nmessages:
\n countdown-start: “&aSer\u00e1s teletransportado en {seconds} segundos…”
\n countdown-remaining: “&aTeletransporte en {seconds} segundos…”
\n teleporting: “&a\u00a1Teletransportando!”
\n teleport-failed: “&cBuscando ubicaci\u00f3n segura…”
\n already-teleported: “&7Ya has sido teletransportado a este mundo anteriormente.”
\n“`<\/p>\n
**Available Messages:**
\n– `countdown-start`: Shown when countdown begins
\n– `countdown-remaining`: Shown each second during countdown
\n– `teleporting`: Shown when teleportation occurs
\n– `teleport-failed`: Shown if location finding fails (shouldn’t happen in normal operation)
\n– `already-teleported`: Shown if player has already been teleported to this world<\/p>\n
## How It Works<\/p>\n
1. When a player enters the configured target world, the plugin checks if they’ve been teleported before
\n2. If not teleported before, a countdown starts (default 3 seconds)
\n3. During the countdown, players see messages indicating when they’ll be teleported
\n4. After the countdown, the plugin finds a random safe location within the configured radius
\n5. The plugin retries indefinitely until a safe location is found
\n6. Once found, the player is teleported using async chunk loading
\n7. The player is marked as teleported for this world (stored in `players.yml`)<\/p>\n
## Safety Features<\/p>\n
The plugin ensures players are teleported to safe locations by:<\/p>\n
– **Solid Ground**: Checking for solid ground below the player
\n– **Air Space**: Ensuring at least 2 blocks of air above the player
\n– **Liquid Avoidance**: Avoiding water and lava blocks
\n– **Void Protection**: Avoiding void locations
\n– **Cave Avoidance**: Only teleporting to locations above Y=60 (avoids caves)
\n– **Infinite Retries**: Retrying indefinitely until a safe location is found<\/p>\n
## Player Data<\/p>\n
Player teleportation status is stored in `plugins\/randomteleport\/players.yml`. This file:<\/p>\n
– Tracks which players have been teleported to which worlds
\n– Auto-saves every 5 minutes
\n– Saves immediately when a player is teleported
\n– Saves on server shutdown<\/p>\n
**To reset a player’s teleportation status:**
\n1. Edit `plugins\/randomteleport\/players.yml`
\n2. Find the player’s UUID entry under `players:`
\n3. Remove the world name from their `worlds:` list, or remove their entire entry
\n4. Save the file<\/p>\n
**To reset all players:**
\n– Delete the `players.yml` file (it will be recreated automatically)<\/p>\n
## Performance<\/p>\n
The plugin is optimized for performance:<\/p>\n
– **Async Chunk Loading**: Uses asynchronous chunk loading to prevent server lag
\n– **Async Location Finding**: Safe location finding runs asynchronously
\n– **Batched Saves**: Player data saves are batched (every 5 minutes)
\n– **Minimal Impact**: Designed to have minimal impact on server performance<\/p>\n
## Troubleshooting<\/p>\n
### Players Not Being Teleported<\/p>\n
– Check that `target-world` matches your world name exactly (case-sensitive)
\n– Verify the world exists and is loaded
\n– Check server logs for errors
\n– Ensure the player hasn’t been teleported before (check `players.yml`)<\/p>\n
### Players Teleported to Unsafe Locations<\/p>\n
– This shouldn’t happen, but if it does, check that the world has valid terrain
\n– Ensure the radius area contains valid terrain (not all void\/water)
\n– Verify the world is properly generated<\/p>\n
### Countdown Not Showing<\/p>\n
– Check that messages are properly configured in `config.yml`
\n– Verify color codes are using `&` not `\u00a7`
\n– Check server console for any errors<\/p>\n
### Reset Player Teleportation Status<\/p>\n
– Edit `plugins\/randomteleport\/players.yml` and remove the player’s UUID entry
\n– Or delete the file to reset all players
\n– Restart the server or wait for the next auto-save<\/p>\n
### Plugin Not Loading<\/p>\n
– Ensure you’re using Paper or Spigot 1.20 or higher
\n– Check that Java 21 or higher is installed
\n– Review server logs for error messages
\n– Verify the JAR file is not corrupted<\/p>\n
## API Version<\/p>\n
– Requires Paper API version 1.20 or higher<\/p>\n
## Commands & Permissions<\/p>\n
This plugin has no commands or permissions – it works automatically based on world changes.<\/p>\n
## Integration<\/p>\n
The plugin provides public getters for managers if you want to integrate with other plugins:<\/p>\n
– `getConfigManager()` – Access configuration
\n– `getPlayerDataManager()` – Access player data
\n– `getTeleportManager()` – Access teleportation logic
\n– `getCountdownManager()` – Access countdown management<\/p>\n
Configuration can be reloaded by calling the `reload()` method via other plugins.<\/p>\n
## Support<\/p>\n
If you encounter any issues or have questions:<\/p>\n
1. Check the troubleshooting section above
\n2. Review server logs for error messages
\n3. Verify your configuration matches the examples
\n4. Ensure you’re using a compatible server version<\/p>\n
## License<\/p>\n
Check the plugin’s license file for information about usage and distribution.<\/p>\n","protected":false},"excerpt":{"rendered":"
Lightweight Paper plugin that automatically teleports players to random safe locations within a configurable area when they first join a specific world. Perfect for survival servers where you want players to start in random locations rather than at spawn.<\/p>\n","protected":false},"featured_media":70441,"template":"","meta":{"_minecraft_slug":"firstjoinrtp","_minecraft_project_id":"TDRxWouD","_minecraft_author":"LeivurGargiulo","_minecraft_license":"MIT","_minecraft_downloads":182,"_minecraft_follows":2,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"firstjoinrtp.zip","_minecraft_size_bytes":15539,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-16T12:57:58.287654Z","_minecraft_date_created":"2025-12-19T10:18:00.660995Z","_minecraft_date_modified":"2025-12-19T05:16:22.134499Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/firstjoinrtp","_minecraft_icon_attachment_id":70441,"_minecraft_imported_at":"2026-06-04T00:12:48+00:00","_minecraft_import_hash":"7d7589f807218a2be1c15d59b72035f2","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,127],"mod_loader":[130,132],"minecraft_version":[59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-70440","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-paper","mod_loader-bukkit","mod_loader-paper","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n