Updated documentation

This commit is contained in:
Intelli 2021-07-15 18:39:41 -06:00
parent ebb5a99cc7
commit 36c2eb3b3f
5 changed files with 589 additions and 14 deletions

446
docs/api/index.md Normal file
View File

@ -0,0 +1,446 @@
# CoreProtect API
The CoreProtect API enables you to log your own block changes, perform lookups, rollbacks, restores, and more.
| API Details | |
| --- | --- |
| **API Version:** | 7 |
| **Plugin Version:** | v20.0+ |
| **Maven:** | [maven.playpro.com](https://maven.playpro.com) |
*Documentation for the previous API version can be found [here](https://www.minerealm.com/community/viewtopic.php?f=32&t=16687).*
---
## Upgrading from API v6
The changes from the previous API version are as follows:
- The following methods have been added:
```java
parseResult(String[] result).getTimestamp()
```
---
- The following methods have been deprecated:
```java
parseResult(String[] result).getTime()
```
---
- The following methods have been removed:
```java
parseResult(String[] result).getTypeId()
```
---
## Getting Started
Ensure you're using CoreProtect 20.0 or higher. Add it as an external jar to your plugin in your IDE.
Alternatively, if using Maven, you can add it via the repository [https://maven.playpro.com](https://maven.playpro.com) (net.coreprotect, 20.0).
The first thing you need to do is get access to CoreProtect. You can do this by using code similar to the following:
```java
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() < 7) {
return null;
}
return CoreProtect;
}
```
With this code, you can then access the API with a call like the following:
```java
CoreProtectAPI api = getCoreProtect();
if (api != null){ // Ensure we have access to the API
api.testAPI(); // Will print out "[CoreProtect] API test successful." in the console.
}
```
Yay, you're now using the CoreProtect API!
---
## API Overview
### Available Methods
```java
boolean isEnabled()
void testAPI()
List<String[]> performLookup(int time, List<String> restrict_users, List<String> exclude_users, List<Object> restrict_blocks, List<Object> exclude_blocks, List<Integer> action_list, int radius, Location radius_location)
List<String[]> performRollback(int time, List<String> restrict_users, List<String> exclude_users, List<Object> restrict_blocks, List<Object> exclude_blocks, List<Integer> action_list, int radius, Location radius_location)
List<String[]> performRestore(int time, List<String> restrict_users, List<String> exclude_users, List<Object> restrict_blocks, List<Object> exclude_blocks, List<Integer> action_list, int radius, Location radius_location)
List<String[]> blockLookup(Block block, int time)
ParseResult parseResult(String[] result)
boolean logChat(Player player, String message)
boolean logCommand(Player player, String command)
boolean logPlacement(String user, Location location, Material type, BlockData blockData)
boolean logRemoval(String user, Location location, Material type, BlockData blockData)
boolean logContainerTransaction(String user, Location location)
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)
void performPurge(int time)
```
### Usage
`isEnabled()`
Calling this will return true if the server has the CoreProtect API enabled, and false if it does not.
---
`testAPI()`
Running this will print out "[CoreProtect] API Test Successful." in the server console.
---
`performLookup(int time, List<String> restrict_users, List<String> exclude_users, List<Object> restrict_blocks, List<Object> exclude_blocks, List<Integer> action_list, int radius, Location radius_location)`
This will perform a lookup.
* **time:** Specify the amount of time to search back. "5" would return results from the last 5 seconds.
* **restrict_users:** Specify any usernames to perform the lookup on. Can be set to "null" if both a radius and a location are specified.
* **exclude_users:** Specify any usernames to exclude from the lookup. Can be set to "null".
* **restrict_blocks:** Specify a list of EntityType's or Material's to restrict the search to. Can be set to "null".
* **exclude_blocks:** Specify a list of EntityType's or Material's to exclude from the search. Can be set to "null".
* **action_list:** Specify a list of action types to restrict the search to. Can be set to "null"
* **radius:** Specify a radius to restrict the search to. A location must be specified if using this. Set to "0" to disable.
* **radius_location:** Specify a location to search around. Can be set to "null" if no radius is specified, and a user is specified.
---
`performRollback(int time, List<String> restrict_users, List<String> exclude_users, List<Object> restrict_blocks, List<Object> exclude_blocks, List<Integer> action_list, int radius, Location radius_location)`
This will perform a rollback. Method must be called async.
* **time:** Specify the amount of time to rollback. "5" would return results from the last 5 seconds.
* **restrict_users:** Specify any usernames to perform the rollback on. Can be set to "null" if both a radius and a location are specified.
* **exclude_users:** Specify any usernames to exclude from the rollback. Can be set to "null".
* **restrict_blocks:** Specify a list of EntityType's or Material's to restrict the rollback to. Can be set to "null".
* **exclude_blocks:** Specify a list of EntityType's or Material's to exclude from the rollback. Can be set to "null".
* **action_list:** Specify a list of action types to restrict the rollback to. Can be set to "null"
* **radius:** Specify a radius to restrict the rollback to. A location must be specified if using this. Set to "0" to disable.
* **radius_location:** Specify a location to rollback around. Can be set to "null" if no radius is specified, and a user is specified.
---
`performRestore(int time, List<String> restrict_users, List<String> exclude_users, List<Object> restrict_blocks, List<Object> exclude_blocks, List<Integer> action_list, int radius, Location radius_location)`
This will perform a restore.
* **time:** Specify the amount of time to restore. "5" would return results from the last 5 seconds.
* **restrict_users:** Specify any usernames to perform the restore on. Can be set to "null" if both a radius and a location are specified.
* **exclude_users:** Specify any usernames to exclude from the restore. Can be set to "null".
* **restrict_blocks:** Specify a list of EntityType's or Material's to restrict the restore to. Can be set to "null".
* **exclude_blocks:** Specify a list of EntityType's or Material's to exclude from the restore. Can be set to "null".
* **action_list:** Specify a list of action types to restrict the restore to. Can be set to "null"
* **radius:** Specify a radius to restrict the restore to. A location must be specified if using this. Set to "0" to disable.
* **radius_location:** Specify a location to restore around. Can be set to "null" if no radius is specified, and a user is specified.
---
`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.
---
`ParseResult parseResult(String[] result)`
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.
* **getType():** Get the Material of the block.
* **getBlockData():** Get the BlockData of the block.
* **getPlayer():** Get the username as a string..
* **getTimestamp():** Get the time of the action.
* **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.
---
`logPlacement(String user, Location location, Material type, BlockData blockData)`
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 Material of the block you're logging.
* **blockData:** Specify the BlockData of the block you're logging. Can be set to "null".
---
`logRemoval(String user, Location location, Material type, BlockData blockData)`
This will log a block as being removed/broken, and will log the block's inventory (if applicable).
* **user:** Specify the username to log as having removed the block.
* **location:** Specify the location of the block you're logging.
* **type:** Specify the Material of the block you're logging.
* **blockData:** Specify the BlockData of the block you're logging. Can be set to "null".
---
`logContainerTransaction(String user, Location location)`
This will log any transactions made to a block's inventory immediately after calling the method.
* **user:** Specify the username to log as having added/removed the items.
* **location:** Specify the location of the block inventory you're logging.
---
`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.
---
`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)
---
`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)
---
`performPurge(int time)`
This will perform a purge on the CoreProtect database.
* **time:** Purge any data earlier than this. "120" would purge any data older than 120 seconds (2 minutes).
---
### Examples
- Get the last 60 seconds of block data for the user "Notch".
```java
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
List<String[]> lookup = CoreProtect.performLookup(60, Arrays.asList("Notch"), null, null, null, null, 0, null);
if (lookup!=null){
for (String[] result : lookup){
ParseResult parseResult = CoreProtect.parseResult(result);
int x = parseResult.getX();
int y = parseResult.getY();
int z = parseResult.getZ();
//...
}
}
}
```
---
- Get the last 60 seconds of block data for the user "Notch", excluding dirt and grass blocks.
```java
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
List<Object> exclude = Arrays.asList(Material.DIRT, Material.GRASS);
List<String[]> lookup = CoreProtect.performLookup(60, Arrays.asList("Notch"), null, null, exclude, null, 0, 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();
//...
}
}
}
```
---
- Get the last 60 seconds of block data within 5 blocks of a location.
```java
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
List<String[]> lookup = CoreProtect.performLookup(60, null, null, null, null, null, 5, location);
if (lookup!=null){
for (String[] value : lookup){
ParseResult result = CoreProtect.parseResult(value);
int x = result.getX();
int y = result.getY();
int z = result.getZ();
//...
}
}
}
```
---
- Rollbacks / restores use the same code structure as the above examples. For example:
```java
class BasicThread implements Runnable {
@Override
public void run() {
try {
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
List<String[]> lookup = CoreProtect.performRollback(60, Arrays.asList("Notch"), null, null, null, null, 0, 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();
//...
}
}
}
}
catch (Exception e){
e.printStackTrace();
}
}
}
Runnable runnable = new BasicThread();
Thread thread = new Thread(runnable);
thread.start();
```
---
- Check if the user "Notch" has already placed a block at a location within the last 60 seconds.
```java
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
boolean hasPlaced = CoreProtect.HasPlaced("Notch", block, 60, 0);
}
```
---
- Get the last 60 seconds of block data for a specific block.
```java
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[] result : lookup){
ParseResult parseResult = CoreProtect.parseResult(value);
int x = parseResult.getX();
int y = parseResult.getY();
int z = parseResult.getZ();
//...
}
}
}
```
---
- Log the placement of a block at a location by the user "Notch".
```java
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
boolean success = CoreProtect.logPlacement("Notch", block.getLocation(), block.getType(), block.getData());
}
```
---
- Log adding/remove items in a chest (or some other block inventory).
```java
CoreProtectAPI CoreProtect = getCoreProtect();
if (CoreProtect!=null){ //Ensure we have access to the API
boolean success = CoreProtect.logContainerTransaction("Notch", inventory.getLocation());
// modify your container contents immediately after (e.g. [i]inventory.addItem(itemStack);[/i])
}
```
---
- 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.
```java
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();
```
---

View File

@ -1,4 +1,4 @@
# CoreProtect Commands
# Commands
---
You can access the commands using either `/coreprotect` or it's aliases `/core` or `/co`.
___
@ -25,7 +25,7 @@ ___
---
## Commands
## Command Details
*Detailed command information is listed below.*
@ -171,12 +171,12 @@ ___
| `a:container` | items taken from or put in chests |
| `a:+container` | items put in chests |
| `a:-container` | items taken from chests |
| `a:inventory` | items dropped or picked up by players |
| `a:+inventory` | items picked up by players |
| `a:-inventory` | items dropped by players |
| `a:item` | items dropped, picked up, taken from, or put in chests |
| `a:+item` | items picked up or put in chests |
| `a:-item` | items dropped or taken from chests |
| `a:inventory` | items dropped, picked up, deposited, or withdrawn by players |
| `a:+inventory` | items picked up or withdrawn by players |
| `a:-inventory` | items dropped or deposited by players |
| `a:item` | merges `a:container` and `a:inventory` |
| `a:+item` | merges `a:+container` and `a:+inventory` |
| `a:-item` | merges `a:-container` and `a:-inventory` |
| `a:kill` | mobs/animals killed |
| `a:session` | player logins/logouts |
| `a:+session` | player logins |

View File

@ -10,14 +10,17 @@ Please be sure to visit the following links for more information.
[**CoreProtect Commands**](/commands/)
A list of all commands that can be used within CoreProtect.
**CoreProtect Permissions**
[**CoreProtect Permissions**](/permissions/)
A list of all permissions that can be used with CoreProtect.
[https://minerealm.com/community/viewtopic.php?f=32&t=6782](https://minerealm.com/community/viewtopic.php?f=32&t=6782)
**CoreProtect API Documentation**
[**CoreProtect API Documentation**](/api/)
Log your own block changes, perform lookups, rollbacks, restores, and more.
[https://minerealm.com/community/viewtopic.php?f=32&t=16687](https://minerealm.com/community/viewtopic.php?f=32&t=16687)
**Compatible Third-Party Plugins & Tools**
[**Compatible Third-Party Plugins & Tools**](/tools-integrations/)
A list of plugins and tools that are compatible with CoreProtect.
[https://dev.bukkit.org/projects/coreprotect/pages/compatible-third-party-plugins-tools](https://dev.bukkit.org/projects/coreprotect/pages/compatible-third-party-plugins-tools)
[**Per-World Configuration Files**](/config/#per-world-configuration)
Log your own block changes, perform lookups, rollbacks, restores, and more.
[**Disable Logging for Specific Users or Commands**](/config/#disabling-logging)
Log your own block changes, perform lookups, rollbacks, restores, and more.

87
docs/permissions.md Normal file
View File

@ -0,0 +1,87 @@
# Permissions
The following permissions can be used to restrict functionality within the plugin.
---
## Base Permissions
* **coreprotect.\*** *(default: op)*
Allows access to all of the CoreProtect commands.
&nbsp;
* **coreprotect.inspect** *(default: op)*
Allows access to the CoreProtect inspect command.
&nbsp;
* **coreprotect.lookup** *(default: op)*
Allows access to the CoreProtect lookup command.
&nbsp;
* **coreprotect.rollback** *(default: op)*
Allows access to the CoreProtect rollback command.
&nbsp;
* **coreprotect.restore** *(default: op)*
Allows access to the CoreProtect restore command.
&nbsp;
* **coreprotect.teleport** *(default: op)*
Allows access to the CoreProtect teleport command.
&nbsp;
* **coreprotect.help** *(default: op)*
Allows access to the CoreProtect help command.
&nbsp;
* **coreprotect.purge** *(default: op)*
Allows access to the CoreProtect purge command.
&nbsp;
* **coreprotect.reload** *(default: op)*
Allows access to the CoreProtect reload command.
&nbsp;
* **coreprotect.status** *(default: op)*
Allows access to the CoreProtect status command.
---
## Child Permissions
* **coreprotect.lookup.block** *(default: op)*
Can be optionally used as a negative permission to prevent block lookups.
&nbsp;
* **coreprotect.lookup.chat** *(default: op)*
Can be optionally used as a negative permission to prevent chat lookups.
&nbsp;
* **coreprotect.lookup.click** *(default: op)*
Can be optionally used as a negative permission to prevent interaction lookups.
&nbsp;
* **coreprotect.lookup.command** *(default: op)*
Can be optionally used as a negative permission to prevent command lookups.
&nbsp;
* **coreprotect.lookup.container** *(default: op)*
Can be optionally used as a negative permission to prevent container lookups.
&nbsp;
* **coreprotect.lookup.item** *(default: op)*
Can be optionally used as a negative permission to prevent item lookups.
&nbsp;
* **coreprotect.lookup.kill** *(default: op)*
Can be optionally used as a negative permission to prevent entity kill lookups.
&nbsp;
* **coreprotect.lookup.near** *(default: op)*
Can be optionally used as a negative permission to prevent lookups via the near command.
&nbsp;
* **coreprotect.lookup.session** *(default: op)*
Can be optionally used as a negative permission to prevent session lookups.
&nbsp;
* **coreprotect.lookup.sign** *(default: op)*
Can be optionally used as a negative permission to prevent sign lookups.
&nbsp;
* **coreprotect.lookup.username** *(default: op)*
Can be optionally used as a negative permission to prevent username change lookups.
---
## Command Handler
* **coreprotect.co** *(default: true)*
Allows access to the CoreProtect "/co" command.
&nbsp;
* **coreprotect.core** *(default: false)*
Allows access to the CoreProtect "/core" command.
&nbsp;
* **coreprotect.coreprotect** *(default: false)*
Allows access to the CoreProtect "/coreprotect" command.

View File

@ -0,0 +1,39 @@
# Tools & Integrations
Listed below are links to plugins and tools compatible with CoreProtect.
These plugins/tools are maintained by third parties, and may have issues outside of our control.
---
## Plugins
* **WorldEdit**
Use WorldEdit selections as a radius, and log your WorldEdit changes.
[https://dev.bukkit.org/projects/worldedit](https://dev.bukkit.org/projects/worldedit)
&nbsp;
* **CoreProtect-Anti-Xray**
Displays how many ores a player has destroyed in a specific time span.
[https://dev.bukkit.org/bukkit-plugins/coreprotect-anti-xray/](https://dev.bukkit.org/bukkit-plugins/coreprotect-anti-xray/)
&nbsp;
## Tools
* **CoreProtect Lookup Web Interface**
Search through your CoreProtect history with an easy-to-use interface.
[https://www.spigotmc.org/resources/coreprotect-lookup-web-interface.28033/](https://www.spigotmc.org/resources/coreprotect-lookup-web-interface.28033/)
&nbsp;
* **Watson**
Watson is a client side Minecraft mod that displays CoreProtect logs in 3D.
[https://github.com/vacla/Watson](https://github.com/vacla/Watson)
&nbsp;
---
Have you created a plugin that's compatible with CoreProtect?
Let us know to have it added to this list!
---