PivotPoly API

Developer documentation for integrating with PivotPoly.

Overview

PivotPoly provides a Java API for plugin developers to programmatically create, manage, and control animated doors.

API Version: 1.0
Minimum Java: 21
Dependencies: None (Paper API only)

Adding PivotPoly as a Dependency

Maven

<dependency>
    <groupId>VexorCore.Logix</groupId>
    <artifactId>pivotpoly</artifactId>
    <version>1.0</version>
    <scope>provided</scope>
</dependency>

Gradle

dependencies {
    compileOnly 'VexorCore.Logix:pivotpoly:1.0'
}

plugin.yml

depend: [PivotPoly]  # Hard dependency
# or
softdepend: [PivotPoly]  # Optional integration

Getting the Plugin Instance

import VexorCore.Logix.pivotPoly.PivotPoly;
import org.bukkit.Bukkit;

public class YourPlugin extends JavaPlugin {
    private PivotPoly pivotPoly;
    
    @Override
    public void onEnable() {
        pivotPoly = (PivotPoly) Bukkit.getPluginManager().getPlugin("PivotPoly");
        
        if (pivotPoly == null) {
            getLogger().warning("PivotPoly not found!");
            return;
        }
        
        getLogger().info("Hooked into PivotPoly v" + pivotPoly.getDescription().getVersion());
    }
}

Core Classes

PivotPoly (Main Class)

public final class PivotPoly extends JavaPlugin {
    public static PivotPoly getInstance();
    public DoorManager getDoorManager();
    public WandListener getWandListener();
    public BlueprintManager getBlueprintManager();
}

Example:

PivotPoly plugin = PivotPoly.getInstance();
DoorManager doorManager = plugin.getDoorManager();

DoorManager

Manages all door operations.

public class DoorManager {
    // Get all doors
    public Map<String, AnimatedDoor> getDoors();
    
    // Create door
    public void createDoor(Player player, String name, WandListener.Selection selection);
    
    // Remove door
    public void removeDoor(String doorName);
    
    // Save/Load
    public void saveDoors();
    public void loadDoors();
    
    // Restore for editing
    public void restoreSelection(Player player, String doorName);
}

Example:

DoorManager manager = PivotPoly.getInstance().getDoorManager();

// Get all doors
Map<String, AnimatedDoor> doors = manager.getDoors();
for (String doorName : doors.keySet()) {
    System.out.println("Door: " + doorName);
}

// Check if door exists
if (manager.getDoors().containsKey("CastleGate")) {
    AnimatedDoor door = manager.getDoors().get("CastleGate");
    // Work with door...
}

AnimatedDoor

Represents an individual animated door.

public class AnimatedDoor {
    // Get door properties
    public String getName();
    public World getWorld();
    public BlockVector3 getPos1();
    public BlockVector3 getPos2();
    public BlockVector3 getPivot();
    
    // Get rotation settings
    public double getRotationAngle();
    public int getAnimationSpeed();
    
    // Get sound settings
    public Sound getOpenSound();
    public Sound getCloseSound();
    
    // Animation control
    public void open();
    public void close();
    public void toggle();
    public boolean isOpen();
}

Example:

AnimatedDoor door = manager.getDoors().get("CastleGate");

if (door != null) {
    // Get properties
    String name = door.getName();
    double angle = door.getRotationAngle();
    
    // Control animation
    if (!door.isOpen()) {
        door.open();
    } else {
        door.close();
    }
    
    // Toggle
    door.toggle();
}

WandListener & Selection

Selection data structure.

public class WandListener {
    public static class Selection {
        public Location pos1;
        public Location pos2;
        public Location pivot;
    }
    
    public Selection getSelection(Player player);
}

Example:

WandListener wandListener = PivotPoly.getInstance().getWandListener();
WandListener.Selection selection = wandListener.getSelection(player);

if (selection.pos1 != null && selection.pos2 != null && selection.pivot != null) {
    // Selection is complete
    // Use for door creation
}

BlueprintManager

Manage door blueprints.

public class BlueprintManager {
    public void saveBlueprint(Player player, String doorName, String blueprintName);
    public void pasteBlueprint(Player player, String newDoorName, String blueprintName);
}

Usage Examples

Example 1: Create Door Programmatically

public void createDoorAPI(Player player, String doorName) {
    PivotPoly plugin = PivotPoly.getInstance();
    WandListener wandListener = plugin.getWandListener();
    DoorManager doorManager = plugin.getDoorManager();
    
    // Get player's current selection
    WandListener.Selection selection = wandListener.getSelection(player);
    
    if (selection.pos1 == null || selection.pos2 == null || selection.pivot == null) {
        player.sendMessage("Please make a complete selection first!");
        return;
    }
    
    // Create the door
    doorManager.createDoor(player, doorName, selection);
    player.sendMessage("Door created: " + doorName);
}

Example 2: Trigger Door Animation

public void triggerDoorByName(String doorName) {
    DoorManager manager = PivotPoly.getInstance().getDoorManager();
    AnimatedDoor door = manager.getDoors().get(doorName);
    
    if (door != null) {
        door.toggle();  // Open if closed, close if open
    } else {
        System.out.println("Door not found: " + doorName);
    }
}

Example 3: List All Doors in World

public List<String> getDoorsInWorld(World world) {
    DoorManager manager = PivotPoly.getInstance().getDoorManager();
    List<String> doorsInWorld = new ArrayList<>();
    
    for (Map.Entry<String, AnimatedDoor> entry : manager.getDoors().entrySet()) {
        AnimatedDoor door = entry.getValue();
        if (door.getWorld().equals(world)) {
            doorsInWorld.add(entry.getKey());
        }
    }
    
    return doorsInWorld;
}

Example 4: Redstone Integration

@EventHandler
public void onRedstoneChange(BlockRedstoneEvent event) {
    Location loc = event.getBlock().getLocation();
    
    // Find nearby door by pivot location
    AnimatedDoor nearbyDoor = findDoorNearLocation(loc, 5);  // 5 block radius
    
    if (nearbyDoor != null) {
        if (event.getNewCurrent() > 0) {
            nearbyDoor.open();
        } else {
            nearbyDoor.close();
        }
    }
}

private AnimatedDoor findDoorNearLocation(Location loc, double radius) {
    DoorManager manager = PivotPoly.getInstance().getDoorManager();
    
    for (AnimatedDoor door : manager.getDoors().values()) {
        Location pivot = door.getPivot().toLocation(door.getWorld());
        if (pivot.distance(loc) <= radius) {
            return door;
        }
    }
    
    return null;
}

Example 5: Door Event Detection

Create custom events when doors open/close:

// Custom event class
public class DoorAnimationEvent extends Event implements Cancellable {
    private final AnimatedDoor door;
    private final boolean opening;
    private boolean cancelled = false;
    
    public DoorAnimationEvent(AnimatedDoor door, boolean opening) {
        this.door = door;
        this.opening = opening;
    }
    
    public AnimatedDoor getDoor() { return door; }
    public boolean isOpening() { return opening; }
    
    @Override
    public boolean isCancelled() { return cancelled; }
    
    @Override
    public void setCancelled(boolean cancel) { this.cancelled = cancel; }
    
    private static final HandlerList handlers = new HandlerList();
    public HandlerList getHandlers() { return handlers; }
    public static HandlerList getHandlerList() { return handlers; }
}

// Call event when door opens/closes
DoorAnimationEvent event = new DoorAnimationEvent(door, true);
Bukkit.getPluginManager().callEvent(event);

if (!event.isCancelled()) {
    door.open();
}

Events

Currently, PivotPoly doesn't fire custom events, but you can hook into:

• PlayerInteractEvent - Detect wand usage
• BlockRedstoneEvent - Trigger doors with redstone

Best Practices

Performance

✅ Cache plugin instance: Don't call getPlugin() repeatedly
✅ Check for null: Always verify doors exist before operations
✅ Async operations: Avoid synchronous long-running tasks

Compatibility

✅ Soft-depend: Use softdepend if integration is optional
✅ Version checks: Verify PivotPoly version compatibility
✅ Null safety: Always check if plugin is loaded

Example Safe Integration

public class MyPlugin extends JavaPlugin {
    private PivotPoly pivotPoly = null;
    
    @Override
    public void onEnable() {
        // Soft-depend integration
        if (Bukkit.getPluginManager().isPluginEnabled("PivotPoly")) {
            pivotPoly = (PivotPoly) Bukkit.getPluginManager().getPlugin("PivotPoly");
            getLogger().info("PivotPoly integration enabled!");
        }
    }
    
    public void usePivotPolyFeature() {
        if (pivotPoly == null) {
            getLogger().warning("PivotPoly not available");
            return;
        }
        
        // Safe to use API
        DoorManager manager = pivotPoly.getDoorManager();
        // ...
    }
}

Future API Additions

Planned for future versions:

• DoorAnimationEvent - Fired when doors open/close
• DoorCreateEvent - Fired when doors are created
• DoorDeleteEvent - Fired when doors are deleted
• Door animation customization API
• Custom animation interpolation functions

Support

For API questions and integration help:

• Discord: Join Discord
• GitHub: Open an issue or discussion

---

Back to: PivotPoly Overview | Home: Documentation Home