Skip to content

API.md

Latest commit

 

History

History
286 lines (219 loc) · 5.95 KB

API.md

File metadata and controls

286 lines (219 loc) · 5.95 KB
Raw

RtpZoneX API Documentation

Using RtpZoneX in Your Plugin

Adding RtpZoneX as a Dependency

Gradle (Kotlin DSL)

repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.mukulx:RtpZoneX:1.0.0")
}

Gradle (Groovy)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.mukulx:RtpZoneX:1.0.0'
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.mukulx</groupId>
        <artifactId>RtpZoneX</artifactId>
        <version>1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Getting the Plugin Instance

import github.mukulx.rtpzonex.RtpZoneX;

RtpZoneX plugin = RtpZoneX.getInstance();

API Examples

Working with Zones

Get a Zone

import github.mukulx.rtpzonex.zone.RtpZone;

RtpZone zone = plugin.getZoneManager().getZone("zoneName");

Get Zone at Location

import org.bukkit.Location;

Location location = player.getLocation();
RtpZone zone = plugin.getZoneManager().getZoneAt(location);

Get All Zones

import java.util.Collection;

Collection<RtpZone> zones = plugin.getZoneManager().getAllZones();

Create a Zone

import org.bukkit.Location;

Location pos1 = new Location(world, x1, y1, z1);
Location pos2 = new Location(world, x2, y2, z2);

boolean success = plugin.getZoneManager().createZone("myZone", pos1, pos2);

Delete a Zone

boolean success = plugin.getZoneManager().deleteZone("zoneName");

Zone Information

Check if Player is in Zone

import java.util.UUID;

UUID playerId = player.getUniqueId();
boolean inZone = zone.hasPlayer(playerId);

Get Players in Zone

import java.util.Set;
import java.util.UUID;

Set<UUID> players = zone.getPlayersInZone();

Get Zone Status

boolean teleporting = zone.isTeleportInProgress();
boolean waiting = zone.isWaitingForPlayers();
int waitTime = zone.getWaitTimeRemaining();

Zone Configuration

Get Zone Config

import github.mukulx.rtpzonex.zone.ZoneConfig;

ZoneConfig config = zone.getConfig();

Modify Zone Settings

config.setTargetWorld("world_nether");
config.setMinDistance(1000);
config.setMaxDistance(10000);
config.setTeleportCountdown(10);
config.setCooldown(120);

// Save changes
plugin.getZoneManager().saveZones();

Teleportation

Start Group Teleport

plugin.getTeleportManager().startGroupTeleport(zone);

Check if Player is Teleporting

boolean isTeleporting = plugin.getTeleportManager().isPlayerTeleporting(player.getUniqueId());

Get Player's Teleport Zone

String zoneName = plugin.getTeleportManager().getPlayerTeleportZone(player.getUniqueId());

Cooldown Management

Check Cooldown

boolean onCooldown = plugin.getCooldownManager().isOnCooldown(player.getUniqueId());

Get Remaining Cooldown

int remaining = plugin.getCooldownManager().getRemainingCooldown(player.getUniqueId());

Set Cooldown

plugin.getCooldownManager().setCooldown(player.getUniqueId());

Remove Cooldown

plugin.getCooldownManager().removeCooldown(player.getUniqueId());

Safe Location Finding

Find Safe Location

import github.mukulx.rtpzonex.teleport.SafeLocationFinder;
import org.bukkit.World;
import java.util.concurrent.CompletableFuture;

SafeLocationFinder finder = plugin.getTeleportManager().getLocationFinder();
World world = Bukkit.getWorld("world");
ZoneConfig config = zone.getConfig();

CompletableFuture<Location> future = finder.findSafeLocation(world, config);
future.thenAccept(location -> {
    if (location != null) {
        // Safe location found
        player.teleport(location);
    } else {
        // No safe location found
        player.sendMessage("No safe location found!");
    }
});

Check if Location is Safe

boolean safe = finder.isSafeLocation(location, config);

Hologram Management

Create Hologram

plugin.getHologramManager().createHologram(zone);

Update Hologram

plugin.getHologramManager().updateHologram(zone);

Remove Hologram

plugin.getHologramManager().removeHologram(zone.getName());

Configuration

Get Config Values

String prefix = plugin.getConfigManager().getPrefix();
String message = plugin.getConfigManager().getMessage("zone-entered");
int countdown = plugin.getConfigManager().getTeleportCountdown();
int cooldown = plugin.getConfigManager().getCooldown();

Reload Configuration

plugin.reload();

Events

RtpZoneX doesn't provide custom events, but you can listen to standard Bukkit events:

@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
    Player player = event.getPlayer();
    RtpZone zone = plugin.getZoneManager().getZoneAt(event.getTo());
    
    if (zone != null) {
        // Player is in a zone
    }
}

Thread Safety

RtpZoneX is designed to be thread-safe and Folia-compatible:

  • Task scheduling uses SchedulerUtil for region handling
  • Entity operations run on the correct region thread
  • Chunk loading is asynchronous
  • Collections are synchronized where needed

When using the API:

  • Use SchedulerUtil for scheduled tasks
  • Execute entity/location operations on the correct thread
  • Use async operations for heavy computations

Best Practices

  1. Always check for null when getting zones or locations
  2. Use CompletableFuture for async operations
  3. Save zones after modifying configurations
  4. Handle exceptions when working with locations
  5. Test on both Paper and Folia if your plugin supports both

Support

For API support:

  • Open an issue on GitHub
  • Check existing documentation
  • Review the source code