# CoderRTP - Complete Documentation

## Table of Contents
1. [Overview](#overview)
2. [Features](#features)
3. [Installation](#installation)
4. [Commands](#commands)
5. [Permissions](#permissions)
6. [Configuration](#configuration)
7. [Placeholders](#placeholders)
8. [API Usage](#api-usage)
9. [Troubleshooting](#troubleshooting)
10. [FAQ](#faq)

---

## Overview

CoderRTP is a professional random teleport plugin designed for Minecraft 1.21.x servers. It provides a beautiful GUI interface, multi-world support, and advanced safety features for the best RTP experience.

**Key Highlights:**
- Multi-world RTP (Overworld, Nether, End)
- Live updating GUI
- Folia compatible
- Optimized performance
- Extensive customization

---

## Features

### Multi-World Support
- **Overworld**: Standard RTP with configurable range (0-1000 blocks default)
- **Nether**: Lava-safe teleportation with proximity checks
- **End**: Teleports to End Cities on outer islands (not dragon area)
- Separate cooldowns per world
- World-specific distance settings

### Beautiful GUI
- Live player count updates
- Real-time ping display
- Hex color support (#RRGGBB)
- Customizable materials and lore
- Auto-updates every second
- Clean, modern design

### Performance
- Async location finding
- Chunk preloading before teleport
- Efficient task management
- Memory-optimized updates
- No server lag

### Safety
- Safe location validation
- Lava/void/hazard protection
- Movement detection (1.0 block threshold)
- Minimum distance between RTPs (100 blocks)
- Same location prevention
- Environment-specific checks

### Advanced
- Per-world cooldowns (60s/90s/120s)
- Configurable delay (5s default)
- Sound effects
- Title and action bar messages
- Tab completion
- Direct world commands
- Bypass permissions

---

## Installation

### Requirements
- Minecraft 1.21.x (1.21, 1.21.1, 1.21.2, 1.21.3, 1.21.4)
- Paper, Spigot, or Folia server
- Java 8 or higher

### Steps
1. Download `CCoderRTP.jar`
2. Stop your server
3. Place jar in `plugins/` folder
4. Start server
5. Plugin generates default configs
6. Edit `plugins/CoderRTP/config.yml`
7. Use `/rtpreload` to reload

### First Time Setup
```bash
# Stop server
./stop.sh

# Copy plugin
cp CCoderRTP.jar plugins/

# Start server
./start.sh

# Wait for generation
# Edit config
nano plugins/CoderRTP/config.yml

# Reload in-game
/rtpreload
```

---

## Commands

### Player Commands

#### `/rtp`
Opens the RTP GUI menu.
- **Permission**: `codertp.use`
- **Aliases**: `randomtp`, `wild`
- **Usage**: `/rtp`

#### `/rtp <world>`
Direct teleport to specified world.
- **Permission**: `codertp.use`
- **Usage**:
- `/rtp overworld` - RTP to Overworld
- `/rtp nether` - RTP to Nether
- `/rtp end` - RTP to End
- **Tab Completion**: Yes

### Admin Commands

#### `/rtpreload`
Reloads plugin configuration.
- **Permission**: `codertp.admin`
- **Usage**: `/rtpreload`

---

## Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `codertp.use` | Use RTP commands | `true` |
| `codertp.admin` | Admin commands | `op` |
| `codertp.bypass` | Bypass cooldowns | `false` |

### Permission Examples

**LuckPerms:**
```
/lp group vip permission set codertp.bypass true
/lp user PlayerName permission set codertp.use true
```

**PermissionsEx:**
```
/pex group vip add codertp.bypass
/pex user PlayerName add codertp.use
```

---

## Configuration

### Main Config (config.yml)

#### GUI Settings
```yaml
gui:
title: "&#2C2F33ʀᴛᴘ ᴍᴇɴᴜ"
buttons:
overworld:
slot: 11 # GUI slot position
material: GRASS_BLOCK # Item material
name: "&#B3FF00ᴏᴠᴇʀᴡᴏʀʟᴅ" # Display name (hex colors)
lore: # Item lore
- "Click to teleport"
- "&7Players: %world_players%"
```

#### RTP Settings
```yaml
settings:
duration: 5 # Countdown time (seconds)
cooldown:
overworld: 60 # Per-world cooldowns
nether: 90
end: 120
distance:
overworld:
min: 0 # Minimum distance from spawn
max: 1000 # Maximum distance from spawn
min-distance-between-rtps: 100 # Blocks between consecutive RTPs
preload-chunks: true # Load chunks before TP
safe-location-checks: true # Validate safe locations
```

#### Messages
```yaml
messages:
teleport:
- "&#FFEE00&lRTP &7» Teleporting in %time%s..."
cancelled:
- "&#FFEE00&lRTP &7» &cTeleport cancelled!"
success:
- "&#FFEE00&lRTP &7» &aTeleported to %world%"
```

#### Sounds
```yaml
sounds:
cancel: "ENTITY_VILLAGER_NO"
teleport: "ENTITY_ENDERMAN_TELEPORT"
countdown: "BLOCK_NOTE_BLOCK_BASS"
volume:
cancel: 1.0
teleport: 1.0
countdown: 1.0
```

#### Display Options
```yaml
send-message:
chat: true # Show chat messages
action-bar: true # Show action bar
title: true # Show titles
```

### Color Codes

**Standard Colors:**
- `&0-9, a-f` - Standard Minecraft colors
- `&l` - Bold
- `&n` - Underline
- `&r` - Reset

**Hex Colors:**
- `&#RRGGBB` - Custom hex colors
- Example: `&#FFEE00` (yellow)

---

## Placeholders

### GUI Placeholders
- `%world_players%` - Number of players in world
- `%ping%` - Simulated world ping

### Message Placeholders
- `%time%` - Countdown/cooldown time
- `%world%` - World name
- `%x%` - X coordinate
- `%y%` - Y coordinate
- `%z%` - Z coordinate

---

## API Usage

### For Developers

**Get RTP Manager:**
```java
CoderRTP plugin = (CoderRTP) Bukkit.getPluginManager().getPlugin("CoderRTP");
TeleportManager rtpManager = plugin.getTeleportManager();
```

**Start RTP:**
```java
Player player = ...;
World world = Bukkit.getWorld("world");
String configWorld = "overworld";
rtpManager.startTeleport(player, world, configWorld);
```

**Check Cooldown:**
```java
long remaining = rtpManager.getRemainingCooldown(player, "overworld");
if (remaining > 0) {
player.sendMessage("Wait " + remaining + " seconds");
}
```

---

## Troubleshooting

### Plugin Won't Load
**Check:**
- Minecraft version is 1.21.x
- Server is Paper/Spigot/Folia
- Java 8+ is installed
- No conflicting plugins

**Console Errors:**
```
[ERROR] Could not load plugin
```
Solution: Check server.log for details

### RTP Not Working
**Check:**
- Player has `codertp.use` permission
- World exists and is loaded
- Cooldown has expired
- No movement during countdown

### False Movement Detection
**Adjust threshold in code:**
```java
// Default: 1.0 blocks
private boolean hasPlayerMoved(Player player, Location startLocation) {
return startLocation.distance(player.getLocation()) > 1.0;
}
```

### GUI Not Updating
**Check:**
- Server TPS is healthy
- No errors in console
- GUI is properly opened

---

## FAQ

### Q: Does it work with Folia?
**A:** Yes! CoderRTP is fully Folia-compatible.

### Q: Can I change the RTP range?
**A:** Yes, edit `config.yml` under `settings.distance`.

### Q: How do I disable cooldowns?
**A:** Set cooldown to `0` or grant `codertp.bypass` permission.

### Q: Can I customize the GUI?
**A:** Yes, fully customizable in `config.yml` under `gui.buttons`.

### Q: Does it support PlaceholderAPI?
**A:** Currently uses internal placeholders. PAPI support planned.

### Q: Can I add more worlds?
**A:** Currently supports Overworld, Nether, End. Custom worlds planned.

### Q: Is it compatible with 1.20.x?
**A:** May work but not officially supported. Use 1.21.x for best experience.

### Q: How do I report bugs?
**A:** Join our Discord: discord.gg/VYFyCtTS

---

## Support

**Discord:** discord.gg/VYFyCtTS
**Developer:** seazon
**Organization:** coderslab

**Before Asking:**
1. Check this documentation
2. Review console errors
3. Try `/rtpreload`
4. Test with default config

---

## Credits

**Developer:** seazon
**Organization:** coderslab
**Version:** 2.0
**License:** Proprietary

© 2026 coderslab - All rights reserved