Skip to content
Arkonix Game Studio edited this page Nov 14, 2026 · 2 revisions

API (Version 13)

Developer API modelled on CoreProtect API v13.

The API follows the structure and method names of the CoreProtect API v13 and lives in the package de.muffin.universalprotect.api.

Important: This is an independent implementation, not a binary drop-in. Plugins written against CoreProtect (package net.coreprotect) do not work unchanged. Code that targets this API must import the classes from de.muffin.universalprotect.api. Migrating usually means changing the imports and the way the API object is obtained.

Getting the API

UniversalProtectAPI api = Bukkit.getServicesManager().load(UniversalProtectAPI.class);
if (api == null || !api.isEnabled() || api.APIVersion() < 13) {
    return;
}

Lookups with the builder

LookupOptions options = LookupOptions.builder()
        .user("Steve")
        .time(3600)                              // seconds
        .radius(location, 20)
        .includeMaterials(List.of(Material.DIAMOND_ORE))
        .blockActions(List.of(LookupOptions.BlockAction.BREAK))
        .limit(0, 50)
        .build();

List<LogResult.BlockResult> results = api.blockLookup(options);

Available lookups

Method Result
blockLookup(options) BlockResult
entityLookup(options) EntityResult
containerLookup(options) ContainerResult
itemLookup(options) ItemResult
inventoryLookup(options) InventoryResult
chatLookup(options), commandLookup(options) MessageResult
signLookup(options) SignResult
sessionLookup(options) SessionResult
usernameLookup(options) UsernameResult

Builder methods

user, users, excludeUsers, time, location, radius, world, limit, includeMaterials, excludeMaterials, includeEntities, excludeEntities, blockActions, entityActions, containerActions, itemActions, inventoryActions, sessionActions, textStartsWithAny, textStartsWithNone.

Logging

Method Purpose
logPlacement(user, ...) Log a block placement
logRemoval(user, ...) Log a block removal
logChat(player, message) Log a chat message
logCommand(player, command) Log a command
logContainerTransaction(user, location) Log the changes of an open container
logInteraction(user, location) Log an interaction
hasPlaced(...), hasRemoved(...) Check whether a user placed or removed a block

PreLogEvent

Fired asynchronously before an entry is saved. It can be cancelled.

@EventHandler
public void onPreLog(PreLogEvent event) {
    if (event.getUser().equals("Notch")) {
        event.setCancelled(true);
    }
}

Warning: The event runs on the database thread. Do not call Bukkit methods that require the main thread inside the handler.

Legacy methods

The String[] based methods (blockLookup(Block, int), performLookup, performRollback, performRestore, performPurge, parseResult) are kept for older plugins.

Fabric edition

The API has the same structure on Fabric. Worlds are identified by dimension ID strings (minecraft:overworld), locations by Loc records and materials by registry IDs (minecraft:stone). This replaces the Bukkit World, Location and Material types of the Paper edition.

UniversalProtectAPI api = UniversalProtect.api();   // de.muffin.universalprotect.UniversalProtect
  • UniversalProtect.api() returns null until the server has started. Declare a dependency in your fabric.mod.json ("universalprotect": "*") and use the jar as a compile-only dependency.
  • Lookups: .radius(new Loc("minecraft:overworld", 0, 64, 0), 20) and .includeMaterials(List.of("minecraft:diamond_ore")).
  • Logging: logChat(user, location, message) and logCommand(user, location, command).
  • PreLogEvent is registered with PreLogEvent.register(event -> { ... }); instead of a Bukkit listener. The event runs on the database thread, so do not touch Minecraft objects (worlds, entities) inside the handler. Schedule that work on the server thread.
  • Legacy methods take a Loc instead of a Block, for example blockLookup(Loc, int).

Related pages: Networking · Migrating from CoreProtect

Clone this wiki locally