Extended CoreProtectPreLogEvent with Action, actionId, material, entityType, and message metadata (implements #846)

docs/api/version/v12.md

@@ -1,35 +1,37 @@
-# API Version 11
+# API Version 12
 
 The CoreProtect API enables you to log your own block changes, perform lookups, rollbacks, restores, and more. 
 
 | API Details |  |
 | --- | --- |
-| **API Version:** | 11 |
-| **Plugin Version:** | v23.1+ |
+| **API Version:** | 12 |
+| **Plugin Version:** | v24.0+ |
 | **Maven:** | [maven.playpro.com](https://maven.playpro.com) |
 
 ---
 
-## Upgrading from API v10
+## Upgrading from API v11
 
 The changes from the previous API version are as follows:
 
-- The following event was extended to include Location (mutable):
+- The following event was extended to include immutable action metadata:
 ```java
-CoreProtectPreLogEvent(String user, Location location)
+CoreProtectPreLogEvent(String user, Location location, CoreProtectPreLogEvent.Action action, int actionId, Material material, EntityType entityType, String message)
 ```
-- The old constructor remains for backward compatibility and is deprecated:
+- The older constructors remain for backward compatibility:
 ```java
 @Deprecated
 CoreProtectPreLogEvent(String user)
+
+CoreProtectPreLogEvent(String user, Location location)
 ```
 
 ---
 
 ## Getting Started
 
-Ensure you're using CoreProtect 23.1 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 (net.coreprotect, 23.1).
+Ensure you're using CoreProtect 24.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 (net.coreprotect, 24.0).
 
 The first thing you need to do is get access to CoreProtect. You can do this by using code similar to the following:
 
@@ -39,7 +41,7 @@ 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;
@@ -52,7 +54,7 @@ private CoreProtectAPI getCoreProtect() {
         }
 
         // Check that a compatible version of the API is loaded
-        if (CoreProtect.APIVersion() < 11) {
+        if (CoreProtect.APIVersion() < 12) {
             return null;
         }
 
@@ -83,9 +85,9 @@ 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)
@@ -133,6 +135,11 @@ Fired when a CoreProtect logger is about to log an action. Cancellable.
 | --- | --- | --- |
 | User | The name of the user under which this action will be logged. | Yes |
 | Location | The location where the action will be logged. | Yes |
+| Action | The type of CoreProtect action being logged. | No |
+| Action ID | The underlying action value for loggers that store one, otherwise `-1`. | No |
+| Material | The material being logged, when applicable. | No |
+| Entity Type | The entity type being logged, when applicable. | No |
+| Message | The message being logged, when applicable. | No |
 | Cancelled | If cancelled, the action won't be logged to the database. | Yes |
 
 ---
@@ -428,7 +435,7 @@ thread.start();
 CoreProtectAPI CoreProtect = getCoreProtect();
 if (CoreProtect != null){ // Ensure we have access to the API
   boolean hasPlaced = CoreProtect.hasPlaced("Notch", block, 60, 0);
-  
+
   // Search queue for pending changes
   if (!hasPlaced){
     List<String[]> lookup = CoreProtect.queueLookup(block);
@@ -527,4 +534,4 @@ Thread thread = new Thread(runnable);
 thread.start();
 ``` 
 
----
+---

src/main/java/net/coreprotect/CoreProtectAPI.java

@@ -41,7 +41,7 @@ public class CoreProtectAPI extends Queue {
     /**
      * Current version of the API
      */
-    private static final int API_VERSION = 11;
+    private static final int API_VERSION = 12;
 
     public static class ParseResult extends net.coreprotect.api.result.ParseResult {
 

src/main/java/net/coreprotect/database/logger/BlockBreakLogger.java

@@ -56,7 +56,7 @@ public class BlockBreakLogger {
                 blockData = overrideData;
             }
 
-            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location);
+            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location, CoreProtectPreLogEvent.Action.BLOCK_BREAK, 0, checkType, null, null);
             if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                 CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
             }

src/main/java/net/coreprotect/database/logger/BlockPlaceLogger.java

@@ -90,7 +90,7 @@ public class BlockPlaceLogger {
                 }
             }
 
-            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, block.getLocation());
+            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, block.getLocation(), CoreProtectPreLogEvent.Action.BLOCK_PLACE, 1, type, null, null);
             if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                 CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
             }

src/main/java/net/coreprotect/database/logger/CommandLogger.java

@@ -29,7 +29,7 @@ public class CommandLogger {
                 return;
             }
 
-            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location);
+            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location, CoreProtectPreLogEvent.Action.PLAYER_COMMAND, -1, null, null, message);
             if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                 CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
             }

src/main/java/net/coreprotect/database/logger/ContainerLogger.java

@@ -249,7 +249,7 @@ public class ContainerLogger extends Queue {
                             metadata = null;
                         }
 
-                        CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location);
+                        CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location, CoreProtectPreLogEvent.Action.CONTAINER_TRANSACTION, action, item.getType(), null, null);
                         if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                             CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
                         }

src/main/java/net/coreprotect/database/logger/EntityKillLogger.java

@@ -43,7 +43,7 @@ public class EntityKillLogger {
             }
 
             Location initialLocation = new Location(block.getWorld(), block.getX(), block.getY(), block.getZ());
-            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, initialLocation);
+            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, initialLocation, CoreProtectPreLogEvent.Action.ENTITY_KILL, 3, null, checkType, null);
             if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                 CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
             }

src/main/java/net/coreprotect/database/logger/ItemLogger.java

@@ -133,7 +133,7 @@ public class ItemLogger {
                         data = null;
                     }
 
-                    CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location);
+                    CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location, CoreProtectPreLogEvent.Action.ITEM_TRANSACTION, action, item.getType(), null, null);
                     if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                         CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
                     }

src/main/java/net/coreprotect/database/logger/PlayerInteractLogger.java

@@ -38,7 +38,7 @@ public class PlayerInteractLogger {
                 return;
             }
 
-            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, block.getLocation());
+            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, block.getLocation(), CoreProtectPreLogEvent.Action.PLAYER_INTERACTION, 2, blockType, null, null);
             if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                 CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
             }

src/main/java/net/coreprotect/database/logger/PlayerKillLogger.java

@@ -6,6 +6,7 @@ import java.util.Locale;
 import org.bukkit.Bukkit;
 import org.bukkit.Location;
 import org.bukkit.block.BlockState;
+import org.bukkit.entity.EntityType;
 
 import net.coreprotect.CoreProtect;
 import net.coreprotect.config.Config;
@@ -32,7 +33,7 @@ public class PlayerKillLogger {
             }
 
             Location initialLocation = new Location(block.getWorld(), block.getX(), block.getY(), block.getZ());
-            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, initialLocation);
+            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, initialLocation, CoreProtectPreLogEvent.Action.PLAYER_KILL, 3, null, EntityType.PLAYER, null);
             if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                 CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
             }

src/main/java/net/coreprotect/database/logger/SignTextLogger.java

@@ -26,7 +26,7 @@ public class SignTextLogger {
                 return;
             }
 
-            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location);
+            CoreProtectPreLogEvent event = new CoreProtectPreLogEvent(user, location, CoreProtectPreLogEvent.Action.SIGN_TEXT, action, null, null, null);
             if (Config.getGlobal().API_ENABLED && !Bukkit.isPrimaryThread()) {
                 CoreProtect.getInstance().getServer().getPluginManager().callEvent(event);
             }

src/main/java/net/coreprotect/event/CoreProtectPreLogEvent.java

@@ -1,21 +1,50 @@
 package net.coreprotect.event;
 
 import org.bukkit.Location;
+import org.bukkit.Material;
+import org.bukkit.entity.EntityType;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 
 public class CoreProtectPreLogEvent extends Event implements Cancellable {
 
+    public enum Action {
+        UNKNOWN,
+        BLOCK_BREAK,
+        BLOCK_PLACE,
+        PLAYER_INTERACTION,
+        ENTITY_KILL,
+        PLAYER_KILL,
+        SIGN_TEXT,
+        CONTAINER_TRANSACTION,
+        ITEM_TRANSACTION,
+        PLAYER_COMMAND
+    }
+
     private static final HandlerList handlers = new HandlerList();
     private boolean cancelled = false;
     private String user;
     private Location location;
+    private final Action action;
+    private final int actionId;
+    private final Material material;
+    private final EntityType entityType;
+    private final String message;
 
     public CoreProtectPreLogEvent(String user, Location location) {
-        super(true); // async
+        this(user, location, Action.UNKNOWN, -1, null, null, null);
+    }
+
+    public CoreProtectPreLogEvent(String user, Location location, Action action, int actionId, Material material, EntityType entityType, String message) {
+        super(true);
         this.user = user;
         this.location = location;
+        this.action = action == null ? Action.UNKNOWN : action;
+        this.actionId = actionId;
+        this.material = material;
+        this.entityType = entityType;
+        this.message = message;
     }
 
     /**
@@ -24,9 +53,7 @@ public class CoreProtectPreLogEvent extends Event implements Cancellable {
      */
     @Deprecated
     public CoreProtectPreLogEvent(String user) {
-        super(true); // async
-        this.user = user;
-        this.location = null;
+        this(user, null);
     }
 
     public String getUser() {
@@ -37,6 +64,26 @@ public class CoreProtectPreLogEvent extends Event implements Cancellable {
         return location;
     }
 
+    public Action getAction() {
+        return action;
+    }
+
+    public int getActionId() {
+        return actionId;
+    }
+
+    public Material getMaterial() {
+        return material;
+    }
+
+    public EntityType getEntityType() {
+        return entityType;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
     @Override
     public boolean isCancelled() {
         return cancelled;