Overview
PlatformLocation represents a location in the underlying platform. It provides access to coordinates (x, y, z), rotation (pitch, yaw), and the world, as well as methods for manipulating locations and calculating distances.
Package: kr.toxicity.model.api.platform
Extends: PlatformRegionHolder
Since: 2.0.0
Core Properties
world()
Returns the world associated with this location.
Returns: The world
Since: 2.0.0
x()
Returns the X coordinate.
Returns: The X coordinate
Since: 2.0.0
y()
Returns the Y coordinate.
Returns: The Y coordinate
Since: 2.0.0
z()
Returns the Z coordinate.
Returns: The Z coordinate
Since: 2.0.0
Rotation
pitch()
Returns the pitch (vertical rotation).
Returns: The pitch in degrees
Since: 2.0.0
yaw()
Returns the yaw (horizontal rotation).
Returns: The yaw in degrees
Since: 2.0.0
Location Manipulation
add()
@NotNull PlatformLocation add(double x, double y, double z)
x - The X offsety - The Y offsetz - The Z offset
Returns: The new location
Since: 2.0.0
Example:
PlatformLocation original = entity.location();
PlatformLocation above = original.add(0, 2, 0); // 2 blocks above
PlatformLocation forward = original.add(5, 0, 0); // 5 blocks forward
Distance Calculations
distance()
default double distance(@NotNull PlatformLocation other)
other - The other location
Returns: The distance
Since: 2.1.0
Example:
PlatformLocation loc1 = entity1.location();
PlatformLocation loc2 = entity2.location();
double dist = loc1.distance(loc2);
if (dist < 5.0) {
System.out.println("Entities are within 5 blocks");
}
distanceSquared()
default double distanceSquared(@NotNull PlatformLocation other)
Use this method instead of distance() when comparing distances, as it avoids the expensive square root calculation.
other - The other location
Returns: The squared distance
Since: 2.1.0
Example:
PlatformLocation playerLoc = player.location();
PlatformLocation targetLoc = target.location();
// More efficient than distance() < 10.0
if (playerLoc.distanceSquared(targetLoc) < 100.0) { // 10^2
System.out.println("Target is within 10 blocks");
}
Task Scheduling
Inherited from PlatformRegionHolder:
task()
@Nullable ModelTask task(@NotNull Runnable runnable)
runnable - The task to run
Returns: The scheduled task, or null if scheduling failed
Since: 2.0.0
taskLater()
@Nullable ModelTask taskLater(long delay, @NotNull Runnable runnable)
delay - The delay in ticksrunnable - The task to run
Returns: The scheduled task, or null if scheduling failed
Since: 2.0.0
Use BukkitAdapter to convert Bukkit locations to PlatformLocation:
import kr.toxicity.model.api.bukkit.platform.BukkitAdapter;
import org.bukkit.Location;
// Convert Bukkit location
Location bukkitLocation = new Location(world, 100, 64, 200, 90f, 0f);
PlatformLocation platformLocation = BukkitAdapter.adapt(bukkitLocation);
// Access coordinates
double x = platformLocation.x(); // 100.0
double y = platformLocation.y(); // 64.0
double z = platformLocation.z(); // 200.0
// Access rotation
float yaw = platformLocation.yaw(); // 90.0
float pitch = platformLocation.pitch(); // 0.0
Usage Examples
Basic Usage
import kr.toxicity.model.api.platform.PlatformLocation;
import kr.toxicity.model.api.platform.PlatformEntity;
public void checkEntityPosition(PlatformEntity entity) {
PlatformLocation loc = entity.location();
// Get coordinates
double x = loc.x();
double y = loc.y();
double z = loc.z();
System.out.println("Entity at: " + x + ", " + y + ", " + z);
// Get rotation
float yaw = loc.yaw();
float pitch = loc.pitch();
System.out.println("Facing: yaw=" + yaw + ", pitch=" + pitch);
}
Distance Checking
public void checkProximity(PlatformEntity entity1, PlatformEntity entity2) {
PlatformLocation loc1 = entity1.location();
PlatformLocation loc2 = entity2.location();
// Calculate distance
double distance = loc1.distance(loc2);
if (distance < 5.0) {
System.out.println("Entities are close!");
}
// More efficient for comparisons
if (loc1.distanceSquared(loc2) < 25.0) { // 5^2
System.out.println("Same check, but faster!");
}
}
Location Offsetting
public void spawnEffectAboveEntity(PlatformEntity entity) {
PlatformLocation baseLoc = entity.location();
// Create location 2 blocks above entity
PlatformLocation effectLoc = baseLoc.add(0, 2, 0);
// Spawn particle or effect at effectLoc
// ...
}
Region-Safe Task Scheduling
public void scheduleLocationTask(PlatformLocation location) {
// Schedule task on location's region (important for Folia)
location.taskLater(20L, () -> {
System.out.println("Task executed at location's region");
// Safely access blocks at this location
});
}
- PlatformEntity - Entity with location
PlatformWorld - World representationPlatformRegionHolder - Region-aware task schedulingModelTask - Scheduled task handle
