From 48cfcb3ea529e79b0ba18fdd4ba768bf6275c75e Mon Sep 17 00:00:00 2001
From: Kam <KamronGaming@gmail.com>
Date: Sun, 11 Jan 2026 17:14:59 -0500
Subject: [PATCH] Add Script Hook Handler for Registering Script Hooks

---
 java/noppes/npcs/api/AbstractNpcAPI.java      | 24 ++++-
 .../npcs/api/handler/IScriptHookHandler.java  | 96 +++++++++++++++++++
 2 files changed, 119 insertions(+), 1 deletion(-)
 create mode 100644 java/noppes/npcs/api/handler/IScriptHookHandler.java

diff --git a/java/noppes/npcs/api/AbstractNpcAPI.java b/java/noppes/npcs/api/AbstractNpcAPI.java
index 027f66a..b6d568b 100644
--- a/java/noppes/npcs/api/AbstractNpcAPI.java
+++ b/java/noppes/npcs/api/AbstractNpcAPI.java
@@ -16,7 +16,21 @@ import noppes.npcs.api.entity.ICustomNpc;
 import noppes.npcs.api.entity.IEntity;
 import noppes.npcs.api.entity.IPlayer;
 import noppes.npcs.api.gui.ICustomGui;
-import noppes.npcs.api.handler.*;
+import noppes.npcs.api.handler.IActionManager;
+import noppes.npcs.api.handler.IAnimationHandler;
+import noppes.npcs.api.handler.IAttributeHandler;
+import noppes.npcs.api.handler.ICloneHandler;
+import noppes.npcs.api.handler.ICustomEffectHandler;
+import noppes.npcs.api.handler.IDialogHandler;
+import noppes.npcs.api.handler.IFactionHandler;
+import noppes.npcs.api.handler.IMagicHandler;
+import noppes.npcs.api.handler.INaturalSpawnsHandler;
+import noppes.npcs.api.handler.IPartyHandler;
+import noppes.npcs.api.handler.IProfileHandler;
+import noppes.npcs.api.handler.IQuestHandler;
+import noppes.npcs.api.handler.IRecipeHandler;
+import noppes.npcs.api.handler.IScriptHookHandler;
+import noppes.npcs.api.handler.ITransportHandler;
 import noppes.npcs.api.handler.data.IAnimation;
 import noppes.npcs.api.handler.data.IFrame;
 import noppes.npcs.api.handler.data.IFramePart;
@@ -151,6 +165,14 @@ public abstract class AbstractNpcAPI {
 
     public abstract IAnimationHandler getAnimations();
 
+    /**
+     * Get the script hook handler for registering custom hooks.
+     * Addon mods can use this to register hooks that will appear in script editor GUIs.
+     *
+     * @return The script hook handler
+     */
+    public abstract IScriptHookHandler getScriptHooks();
+
     public abstract String[] getAllBiomeNames();
 
     public abstract ICustomNpc<?> createNPC(IWorld var1);
diff --git a/java/noppes/npcs/api/handler/IScriptHookHandler.java b/java/noppes/npcs/api/handler/IScriptHookHandler.java
new file mode 100644
index 0000000..37df4b5
--- /dev/null
+++ b/java/noppes/npcs/api/handler/IScriptHookHandler.java
@@ -0,0 +1,96 @@
+package noppes.npcs.api.handler;
+
+import java.util.List;
+
+/**
+ * Handler for registering and retrieving script hooks.
+ * Addon mods can register custom hooks that will appear in the script editor GUIs.
+ *
+ * Available contexts:
+ * - "npc" - NPC script editor
+ * - "player" - Player scripts editor
+ * - "block" - Scripted block editor
+ * - "item" - Scripted item editor
+ * - "linked_item" - Linked item editor
+ * - "forge" - Forge scripts editor
+ * - "global_npc" - Global NPC scripts editor
+ * - "recipe" - Recipe scripts editor
+ * - "effect" - Custom effect scripts editor
+ */
+public interface IScriptHookHandler {
+
+    // Context constants
+    String CONTEXT_NPC = "npc";
+    String CONTEXT_PLAYER = "player";
+    String CONTEXT_BLOCK = "block";
+    String CONTEXT_ITEM = "item";
+    String CONTEXT_LINKED_ITEM = "linked_item";
+    String CONTEXT_FORGE = "forge";
+    String CONTEXT_GLOBAL_NPC = "global_npc";
+    String CONTEXT_RECIPE = "recipe";
+    String CONTEXT_EFFECT = "effect";
+
+    /**
+     * Register a hook for a single context.
+     *
+     * @param context The context identifier (e.g., "npc", "player", "block")
+     * @param functionName The script function name (e.g., "onMyCustomEvent")
+     */
+    void registerHook(String context, String functionName);
+
+    /**
+     * Register a hook for multiple contexts at once.
+     *
+     * @param functionName The script function name
+     * @param contexts The contexts where this hook should appear
+     */
+    void registerHooks(String functionName, String... contexts);
+
+    /**
+     * Unregister a hook from a specific context.
+     *
+     * @param context The context to remove the hook from
+     * @param functionName The function name to remove
+     */
+    void unregisterHook(String context, String functionName);
+
+    /**
+     * Unregister a hook from all contexts.
+     *
+     * @param functionName The function name to remove
+     */
+    void unregisterHookFromAll(String functionName);
+
+    /**
+     * Get all registered addon hooks for a context.
+     * This does not include built-in hooks.
+     *
+     * @param context The context identifier
+     * @return List of hook function names for that context
+     */
+    List<String> getAddonHooks(String context);
+
+    /**
+     * Get all hooks (built-in + addon) for a context.
+     *
+     * @param context The context identifier
+     * @return List of all hook function names for that context
+     */
+    List<String> getAllHooks(String context);
+
+    /**
+     * Check if a hook is registered in a specific context.
+     *
+     * @param context The context to check
+     * @param functionName The function name to look for
+     * @return true if the hook is registered
+     */
+    boolean hasHook(String context, String functionName);
+
+    /**
+     * Get all available context identifiers.
+     *
+     * @return Array of context strings
+     */
+    String[] getContexts();
+}