MineRealm Community It is currently Sat Nov 01, 2014 2:09 am

 [ 2 posts ] 
 CoreProtect - API [v2] 
Author Message
Site Admin
User avatar

Joined:   Dec 3, 2010
Posts:   2,896

Verified IGN:
Intelli

User Reputation:  
7/10


Reply with quote
Post CoreProtect - API [v2]
CoreProtect API v2

The CoreProtect API enables you to log your own block changes, perform lookups, rollbacks, restores, and more. This is for advanced plugin developers.

Upgrading From API v1
The only changes from the previous API version are as follows:

  • 1. The following code no longer works:
    Code:
    // Check that a compatible version of CoreProtect is loaded
    if (Double.parseDouble(plugin.getDescription().getVersion()) < 1.6){
      return null;
    }

  • 2. It is now recommended that you perform the following check when connecting to the API:
    Code:
    // Check that a compatible version of the API is loaded
    if (CoreProtect.APIVersion() < 2){
        return null;
    }

Getting Started

Ensure you're using CoreProtect 2.0.8 or higher. Add it as an external jar to your plugin in your IDE.

The first thing you need to do is get access to CoreProtect. You can do this by using code similar to the following:

Code:
import net.coreprotect.CoreProtect;
import net.coreprotect.CoreProtectAPI;

private CoreProtectAPI getCoreProtect() {
Plugin plugin = getServer().getPluginManager().getPlugin("CoreProtect");
     
// Check that CoreProtect is loaded
if (plugin == null || !(plugin instanceof CoreProtect)) {
    return null;
}
       
// Check that the API is enabled
CoreProtectAPI CoreProtect = ((CoreProtect)plugin).getAPI();
if (CoreProtect.isEnabled()==false){
    return null;
}

// Check that a compatible version of the API is loaded
if (CoreProtect.APIVersion() < 2){
    return null;
}
         
return CoreProtect;
}


With this code, you can then access the API with a call like the following:

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  CoreProtect.testAPI(); //Will print out "[CoreProtect] API Test Successful." in the console.
}


Hooray, you're now using the CoreProtect API!

Quick Documentation

Available functions:
Code:
boolean isEnabled()

void testAPI()

List<String[]> performLookup(String user, int time, int radius, Location location, List<Integer> restrict, List<Integer> exclude)

List<String[]> performRollback(String user, int time, int radius, Location location, List<Integer> restrict, List<Integer> exclude)

List<String[]> performRestore(String user, int time, int radius, Location location, List<Integer> restrict, List<Integer> exclude)

List<String[]> blockLookup(Block block, int time)

ParseResult parseResult(String[] data)

boolean logPlacement(String user, Location location, int type, byte data)

boolean logRemoval(String user, Location location, int type, byte data)

boolean logInteraction(String user, Location location)

boolean hasPlaced(String user, Block block, int time, int offset)

boolean hasRemoved(String user, Block block, int time, int offset)


Usage:

Quote:
isEnabled()

Calling this will return true if the server has the CoreProtect API enabled, and false if it does not.

--

Quote:
testAPI()

Running this will print out "[CoreProtect] API Test Successful." in the server console.

--

Quote:
performLookup(String user, int time, int radius, Location location, List<Integer> restrict, List<Integer> exclude)

This will perform a lookup.
  • user: Specify a username to perform a lookup on. Can be set to "null" if both a radius and a location are specified.
  • time: Specify the amount of time to search back. "5" would return results from the last 5 seconds.
  • radius: Specify a radius to restrict the search to. A location must be specified if using this. Set to "0" to disable.
  • location: Specify a location to search around. Can be set to "null" if no radius is specified, and a user is specified.
  • restrict: Specify a list of block ID's to restrict the search to. Can be set to "null"
  • exclude: Specify a list of block ID's to exclude from the search. Can be set to "null"

--

Quote:
performRollback(String user, int time, int radius, Location location, List<Integer> restrict, List<Integer> exclude)

This will perform a rollback.
  • user: Specify a username to perform a rollback on. Can be set to "null" if both a radius and a location are specified.
  • time: Specify the amount of time to rollback. "5" would return results from the last 5 seconds.
  • radius: Specify a radius to restrict the rollback to. A location must be specified if using this. Set to "0" to disable.
  • location: Specify a location to rollback around. Can be set to "null" if no radius is specified, and a user is specified.
  • restrict: Specify a list of block ID's to restrict the rollback to. Can be set to "null"
  • exclude: Specify a list of block ID's to exclude from the rollback. Can be set to "null"

--

Quote:
performRestore(String user, int time, int radius, Location location, List<Integer> restrict, List<Integer> exclude)

This will perform a restore.
  • user: Specify a username to perform a restore on. Can be set to "null" if both a radius and a location are specified.
  • time: Specify the amount of time to restore. "5" would return results from the last 5 seconds.
  • radius: Specify a radius to restrict the restore to. A location must be specified if using this. Set to "0" to disable.
  • location: Specify a location to restore around. Can be set to "null" if no radius is specified, and a user is specified.
  • restrict: Specify a list of block ID's to restrict the restore to. Can be set to "null"
  • exclude: Specify a list of block ID's to exclude from the restore. Can be set to "null"

--

Quote:
blockLookup(Block block, int time)

This will perform a full lookup on a single block.
  • block: The block to perform the lookup on.
  • time: Specify the amount of time to lookup. "5" would return results from the last 5 seconds.

--

Quote:
ParseResult parseResult(String[] data)

This will parse results from a lookup. You'll then be able to view the following:
  • getX(): Get the X coordinate of the block.
  • getY(): Get the Y coordinate of the block.
  • getZ(): Get the Z coordinate of the block.
  • getTypeId(): Get the type ID of the block.
  • getData(): Get the byte data of the block.
  • getActionId(): Get the action ID. (0=removed, 1=placed, 2=interaction)
  • getActionString(): Get the action as a string. (Removal, Placement, Interaction)
  • isRolledBack(): If the block is currently rolled back or not.
  • worldName(): The name of the world the block is located in.

--

Quote:
logPlacement(String user, Location location, int type, byte data)

This will log a block as being placed.
  • user: Specify the username to log as having placed the block.
  • location: Specify the location of the block you're logging.
  • type: Specify the type ID of the block you're logging.
  • data: Specify the byte data value of the block you're logging.

--

Quote:
logRemoval(String user, Location location, int type, byte data)

This will log a block as being removed/broken.
  • user: Specify the username to log as having removed the block.
  • location: Specify the location of the block you're logging.
  • type: Specify the type ID of the block you're logging.
  • data: Specify the byte data value of the block you're logging.

--

Quote:
logInteraction(String user, Location location)

This will log a block as having been interacted with.
  • user: Specify the username to log as having caused the interaction.
  • location: Specify the location of the interaction you're logging.

--

Quote:
hasPlaced(String user, Block block, int time, int offset)

This will return true if a user has already placed a block at the location within the specified time limit.
  • user: The username you're checking to see if they've placed a block already.
  • block: The block you're checking.
  • time: How far back to check. "5" would only check through the last 5 seconds of logged blocks.
  • offset: A time offset. "2" would ignore the last 2 seconds of most recently ignored data. (0=no offset)

--

Quote:
hasRemoved(String user, Block block, int time, int offset)

This will return true if a user has already removed a block at the location within the specified time limit.
  • user: The username you're checking to see if they've removed a block already.
  • block: The block you're checking.
  • time: How far back to check. "5" would only check through the last 5 seconds of logged blocks.
  • offset: A time offset. "2" would ignore the last 2 seconds of most recently ignored data. (0=no offset)

Examples

1. Get the last 60 seconds of block data for the user "Notch".

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  List<String[]> lookup = CoreProtect.performLookup("Notch", 60, 0, null, null, null);
  if (lookup!=null){
    for (String[] value : lookup){
      ParseResult result = CoreProtect.parseResult(value);
      int x = result.getX();
      int y = result.getY();
      int z = result.getZ();
      //...
    }
  }
}


--

2. Get the last 60 seconds of block data for the user "Notch", excluding dirt and grass blocks.

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  List<Integer> exclude = Arrays.asList(2,3);
  List<String[]> lookup = CoreProtect.performLookup("Notch", 60, 0, null, null, exclude);
  if (lookup!=null){
    for (String[] value : lookup){
      ParseResult result = CoreProtect.parseResult(value);
      int x = result.getX();
      int y = result.getY();
      int z = result.getZ();
      //...
    }
  }
}


--

3. Get the last 60 seconds of block data within 5 blocks of a location.

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  List<String[]> lookup = CoreProtect.performLookup(null, 60, 5, location, null, null);
  if (lookup!=null){
    for (String[] value : lookup){
      ParseResult result = CoreProtect.parseResult(value);
      int x = result.getX();
      int y = result.getY();
      int z = result.getZ();
      //...
    }
  }
}


--

4. Rollbacks / restores use the same code structure as the above examples. For example:

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  List<String[]> lookup = CoreProtect.performRollback("Notch", 60, 0, null, null, null);
  if (lookup!=null){
    for (String[] value : lookup){
      ParseResult result = CoreProtect.parseResult(value);
      int x = result.getX();
      int y = result.getY();
      int z = result.getZ();
      //...
    }
  }
}


--

5. Check if the user "Notch" has already placed a block at a location within the last 60 seconds.

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  boolean hasplaced = CoreProtect.HasPlaced("Notch", block, 60, 0);
}


--

6. Get the last 60 seconds of block data for a specific block.

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  List<String[]> lookup = CoreProtect.blockLookup(block, 60);
  if (lookup!=null){
    for (String[] value : lookup){
      ParseResult result = CoreProtect.parseResult(value);
      int x = result.getX();
      int y = result.getY();
      int z = result.getZ();
      //...
    }
  }
}


--

7. Log the placement of a block at a location by the user "Notch".

Code:
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
  boolean success = CoreProtect.logPlacement("Notch", block.getLocation(), block.getTypeId(), block.getData());
}


--

8. Perform a multi-threaded placement check to see if the user "Notch" has already placed a block at a location within the last 60 seconds. This ignores the most recent 1 second of logged data, to account for the fact that that new block data may have already been logged, depending on your code.

Code:
final Block block = null; //Should be an actual block
class BasicThread implements Runnable {
  @Override
  public void run() {
    try {
      CoreProtectAPI CoreProtect = getCoreProtect();
      if (CoreProtect!=null){ //Ensure we have access to the API
        boolean hasplaced = CoreProtect.hasPlaced("Notch", block, 60, 1);
      }
    }
    catch (Exception e){
      e.printStackTrace();
    }
  }
}
Runnable runnable = new BasicThread();
Thread thread = new Thread(runnable);
thread.start();

_________________
"When you do things right, people won't be sure you've done anything at all."
Mon Jul 01, 2013 10:47 pm
Profile

Joined:   Dec 3, 2010
Posts:   188

Verified IGN:
Unknown

User Reputation:  
0/10


Reply with quote
Post Re: CoreProtect - API [v2]
Is there an api for hooking into the rollback event or logging custom inventory transactions from forge mods like applied energistics?
Wed Mar 05, 2014 2:26 pm
Display posts from previous:  Sort by  
Post new topic Post new reply  [ 2 posts ] 


Who is online

Users browsing this forum: No registered users and 1 guest