API

The API is in our repository: repo.incredibleplugins.com

Javadoc

The Javadoc can be found here: repo.incredibleplugins.com

Getting the API instance

The API is accessible through an implementation of the ChestProtectAPI interface. Access it after ChestProtect is loaded (e.g. in onEnable):

ChestProtectAPI api = ChestProtectAPI.getInstance();

Calling getInstance() before ChestProtect is loaded throws a NullPointerException. If you used softdepend, guard the call with a null-check on Bukkit.getPluginManager().getPlugin("ChestProtect").

---

Checking and looking up protections

Is a block or entity protectable?

ProtectionManager manager = api.getProtectionManager();

boolean canProtectBlock  = manager.isProtectableBlock(Material.CHEST);
boolean canProtectEntity = manager.isProtectableEntity(EntityType.ITEM_FRAME);

Look up a block protection

// By Block object
BlockProtection protection = api.getBlockProtectionByBlock(block); // null if not protected

// By world + coordinates
ProtectionWorld world = api.getProtectionWorld(bukkitWorld);
if (world != null) {
    BlockProtection protection = world.getBlockProtection(x, y, z);
}

Look up an entity protection

EntityProtection protection = api.getEntityProtection(entity); // null if not protected

---

Working with protections

Every BlockProtection and EntityProtection extends Protection, which provides:

UUID owner      = protection.getOwner();
boolean trusted = protection.isTrusted(playerUUID);
String name     = protection.getDisplayName(); // player-defined name, may be null

// Trust / untrust
protection.trustPlayer(playerUUID);
protection.untrustPlayer(playerUUID);

// Flags (e.g. PUBLIC_TAKE, REDSTONE, HOLOGRAM)
boolean isPublic = protection.hasFlag(ProtectionFlag.PUBLIC_TAKE);
protection.toggleFlag(ProtectionFlag.PUBLIC_TAKE);

// Delete
protection.delete(protectPlayer);        // sends unlock message to deleter
protection.delete(protectPlayer, false); // silent delete

---

Creating protections

You must provide a ProtectionHook that identifies your plugin as the creator. Protections created by a hook are automatically deleted if the owning plugin has not been active for 30 days.

1. Implement ProtectionHook

public class MyHook extends ProtectionHook {

    public MyHook(Plugin plugin) {
        super(plugin);
    }

    @Override
    public boolean hasItem(ItemStack item) {
        // Return true if this item belongs to your plugin.
        // ChestProtect uses this to skip auto-lock for your custom items.
        return false;
    }
}

2. Register the hook on enable

@Override
public void onEnable() {
    myHook = new MyHook(this);
    myHook.register();
}

3. Create a protection

ProtectionManager manager = api.getProtectionManager();
ProtectPlayer protectPlayer = api.getProtectPlayer(player); // must be online

if (manager.isProtectableBlock(block.getType())) {
    BlockProtection protection = manager.createBlockProtection(myHook, block, protectPlayer);
}

if (manager.isProtectableEntity(entity.getType())) {
    EntityProtection protection = manager.createEntityProtection(myHook, entity, protectPlayer);
}

createBlockProtection / createEntityProtection throw IllegalArgumentException if the block or entity type is not protectable, and IllegalStateException if the block or entity is already protected.

---

Player data

Online player

ProtectPlayer protectPlayer = api.getProtectPlayer(player); // null if unloaded
int blockCount  = protectPlayer.getBlockProtectionsAmount();
int entityCount = protectPlayer.getEntityProtectionsAmount();

Offline player

Offline player data is fetched asynchronously from the database:

api.getProtectOfflinePlayer(uuid).thenAccept(offlinePlayer -> {
    if (offlinePlayer.hasData()) {
        int blockCount = offlinePlayer.getBlockProtectionsAmount();
    }
});

Player flags

boolean autoLock = protectPlayer.hasFlag(PlayerFlag.AUTO_LOCK);
protectPlayer.toggleFlag(PlayerFlag.NOTIFICATIONS);

---

Events

Listen to ChestProtect events the same way as any Bukkit event:

Event	Fired when
ProtectionPreCreationEvent	Before a protection is created — cancellable
ProtectionCreatedEvent	After a protection has been created
ProtectionDeletedEvent	After a protection has been deleted
PlayerOpenProtectionEvent	When a player opens a protection — cancellable
ProtectionChunkAddedEvent	A chunk receives its first protection
ProtectionChunkDeletedEvent	The last protection in a chunk is deleted

@EventHandler
public void onProtectionCreated(ProtectionCreatedEvent event) {
    Protection protection = event.getProtection();
    // ...
}

@EventHandler
public void onProtectionPreCreation(ProtectionPreCreationEvent event) {
    if (someCondition) {
        event.setCancelled(true);
    }
}