docs: add hook API tutorials for Lua, Python, Go, and Rust

Add comprehensive documentation for mod developers using the gregCore Hook API. The tutorials cover subscribing to and firing hooks for each supported language (Lua, Python, Go, and Rust), including code examples and troubleshooting guidance.
2026-04-20 14:50:38 +02:00
parent 84b6f56a50
commit 9819687e9f
7 changed files with 284 additions and 17 deletions
@@ -0,0 +1,55 @@
+# C# Hook API Tutorial
+
+In C# mods, you'll use the `gregCore.Sdk.IGregAPI` interface to interact with the Hook API.
+
+## Subscribing to a Hook
+
+To listen for an event, you'll use the `On` method in your `MelonMod`.
+
+```csharp
+using gregCore.Sdk;
+using gregCore.Sdk.Models;
+
+namespace MyCsharpMod;
+
+public class MyMod : MelonMod
+{
+    private IGregAPI _api;
+
+    public override void OnInitializeMelon()
+    {
+        // Get the SDK API instance
+        _api = GregAPI.GetSdkApi();
+
+        // Subscribe to a hook
+        _api.On("greg.PLAYER.CoinChanged", OnCoinChanged);
+    }
+
+    private void OnCoinChanged(GregPayload payload)
+    {
+        var amount = payload.GetValue<float>("Amount");
+        var total = payload.GetValue<float>("Total");
+        _api.LogInfo($"Money changed! Amount: {amount}, Total: {total}");
+    }
+}
+```
+
+## Firing a Hook
+
+To fire a custom event from your C# mod, use the `Fire` method.
+
+```csharp
+// Fire a custom hook from C#
+var payload = new GregPayload("greg.CUSTOM.MyEvent", "MyCsharpMod");
+payload.Data["foo"] = "bar";
+payload.Data["value"] = 42;
+
+_api.Fire("greg.CUSTOM.MyEvent", payload);
+```
+
+## Troubleshooting
+
+- Ensure your C# mod is a `MelonMod`.
+- Reference the `gregCore.dll` and `gregCore.Sdk` namespaces.
+- Use `GregAPI.GetSdkApi()` to get the API instance.
+- Ensure the hook name starts with `greg.`.
@@ -0,0 +1,52 @@
+# Go Hook API Tutorial
+
+In Go mods, you'll use the `greg-go` package (or raw FFI via the `GregCoreAPI` struct) to interact with the Hook API.
+
+## Subscribing to a Hook
+
+To listen for an event, you'll use the `greg_mod_init` entry point to register your callbacks.
+
+```go
+// Example of a Go hook subscription
+//export onHookCallback
+func onHookCallback(hookName, trigger, jsonData *C.char) {
+    hookNameStr := C.GoString(hookName)
+    triggerStr := C.GoString(trigger)
+    jsonDataStr := C.GoString(jsonData)
+
+    fmt.Printf("Hook received: %s (Trigger: %s) - Data: %s\n", hookNameStr, triggerStr, jsonDataStr)
+}
+
+//export greg_mod_init
+func greg_mod_init(api *GregCoreAPI) bool {
+    // Subscribe to a hook
+    hookName := C.CString("greg.PLAYER.CoinChanged")
+    defer C.free(unsafe.Pointer(hookName))
+    
+    api.OnHook(hookName, (unsafe.Pointer)(C.onHookCallback))
+    
+    return true
+}
+```
+
+## Firing a Hook
+
+To fire a custom event from your Go mod, use the `FireHook` function pointer in the `GregCoreAPI` struct.
+
+```go
+// Fire a custom hook from Go
+hookName := C.CString("greg.CUSTOM.MyEvent")
+defer C.free(unsafe.Pointer(hookName))
+
+jsonData := C.CString(`{"foo": "bar", "value": 42}`)
+defer C.free(unsafe.Pointer(jsonData))
+
+api.FireHook(hookName, jsonData)
+```
+
+## Troubleshooting
+
+- Ensure your Go DLL is located in `Plugins/Go/`.
+- Your Go mod must export `greg_mod_info` and `greg_mod_init`.
+- Use the `greg-go` package for a more ergonomic API.
+- Ensure the hook name starts with `greg.`.
@@ -0,0 +1,38 @@
+# JavaScript/TypeScript Hook API Tutorial
+
+In JS mods, the `greg` global object is automatically provided to interact with the gregCore Hook API.
+
+## Subscribing to a Hook
+
+To listen for an event, use `greg.on(hookName, callback)`.
+
+```javascript
+// Register a mod
+greg.logInfo("My JS Mod initializing...");
+
+// Subscribe to the player's coin changed hook
+greg.on("greg.PLAYER.CoinChanged", (payload) => {
+    const amount = payload.Data.Amount;
+    const total = payload.Data.Total;
+    greg.logInfo(`Money changed! Amount: ${amount}, Total: ${total}`);
+});
+```
+
+## Firing a Hook
+
+To fire a custom event from your JS mod, use `greg.fire(hookName, dataObject)`.
+
+```javascript
+// Fire a custom hook from JS
+greg.fire("greg.CUSTOM.MyEvent", {
+    foo: "bar",
+    value: 42
+});
+```
+
+## Troubleshooting
+
+- Ensure your JS file is located in `Plugins/Js/`.
+- Check the `MelonLoader` console for any JS errors or log messages from `JsBridge`.
+- Ensure the hook name starts with `greg.`.
+- Use Jint for a performant JS engine.
@@ -0,0 +1,37 @@
+# Lua Hook API Tutorial
+
+In Lua mods, the `greg` global object is automatically provided to interact with the gregCore Hook API.
+
+## Subscribing to a Hook
+
+To listen for an event, use `greg.on(hookName, callback)`.
+
+```lua
+-- Register a mod
+greg.log_info("My Lua Mod initializing...")
+
+-- Subscribe to the player's coin changed hook
+greg.on("greg.PLAYER.CoinChanged", function(payload)
+    local amount = payload.data["Amount"]
+    local total = payload.data["Total"]
+    greg.log_info("Money changed! Amount: " .. tostring(amount) .. ", Total: " .. tostring(total))
+end)
+```
+
+## Firing a Hook
+
+To fire a custom event from your Lua mod, use `greg.fire(hookName, dataTable)`.
+
+```lua
+-- Fire a custom hook
+greg.fire("greg.CUSTOM.MyEvent", {
+    foo = "bar",
+    value = 42
+})
+```
+
+## Troubleshooting
+
+- Ensure your `main.lua` file is located in `Plugins/Lua/<ModId>/`.
+- Check the `MelonLoader` console for any Lua errors or log messages from `LuaFFIBridge`.
+- Ensure the hook name starts with `greg.`.
@@ -0,0 +1,40 @@
+# Python Hook API Tutorial
+
+In Python mods, the `greg` global object is automatically provided to interact with the gregCore Hook API.
+
+## Subscribing to a Hook
+
+To listen for an event, use `greg.on(hookName, callback)`.
+
+```python
+# My Python Mod initializing...
+greg.log_info("My Python Mod initializing...")
+
+# Define a callback function
+def on_coin_changed(payload):
+    amount = payload["data"]["Amount"]
+    total = payload["data"]["Total"]
+    greg.log_info(f"Money changed! Amount: {amount}, Total: {total}")
+
+# Subscribe to the player's coin changed hook
+greg.on("greg.PLAYER.CoinChanged", on_coin_changed)
+```
+
+## Firing a Hook
+
+To fire a custom event from your Python mod, use `greg.fire(hookName, dataDict)`.
+
+```python
+# Fire a custom hook
+greg.fire("greg.CUSTOM.MyEvent", {
+    "foo": "bar",
+    "value": 42
+})
+```
+
+## Troubleshooting
+
+- Ensure your `main.py` file is located in `Plugins/Python/<ModId>/`.
+- Check the `MelonLoader` console for any Python errors or log messages from `PythonFFIBridge`.
+- Ensure the hook name starts with `greg.`.
+- Make sure `python310.dll` is available (configurable in `gregCore` config).
@@ -0,0 +1,47 @@
+# Rust Hook API Tutorial
+
+In Rust mods, you'll use the `greg-rs` crate (or raw FFI via the `GregCoreAPI` struct) to interact with the Hook API.
+
+## Subscribing to a Hook
+
+To listen for an event, you'll use the `greg_mod_init` entry point to register your callbacks.
+
+```rust
+// Example of a Rust hook subscription
+extern "C" fn on_hook_callback(hook_name: *const i8, trigger: *const i8, json_data: *const i8) {
+    let hook_name = unsafe { CStr::from_ptr(hook_name).to_string_lossy() };
+    let trigger = unsafe { CStr::from_ptr(trigger).to_string_lossy() };
+    let json_data = unsafe { CStr::from_ptr(json_data).to_string_lossy() };
+
+    println!("Hook received: {} (Trigger: {}) - Data: {}", hook_name, trigger, json_data);
+}
+
+#[no_mangle]
+pub extern "C" fn greg_mod_init(api: *const GregCoreAPI) -> bool {
+    let api = unsafe { &*api };
+    
+    // Subscribe to a hook
+    let hook_name = CString::new("greg.PLAYER.CoinChanged").unwrap();
+    (api.on_hook)(hook_name.as_ptr(), on_hook_callback as *const ());
+    
+    true
+}
+```
+
+## Firing a Hook
+
+To fire a custom event from your Rust mod, use the `fire_hook` function pointer in the `GregCoreAPI` struct.
+
+```rust
+// Fire a custom hook from Rust
+let hook_name = CString::new("greg.CUSTOM.MyEvent").unwrap();
+let json_data = CString::new(r#"{"foo": "bar", "value": 42}"#).unwrap();
+(api.fire_hook)(hook_name.as_ptr(), json_data.as_ptr());
+```
+
+## Troubleshooting
+
+- Ensure your Rust DLL is located in `Plugins/Rust/`.
+- Your Rust mod must export `greg_mod_info` and `greg_mod_init`.
+- Use the `greg-rs` crate for a more ergonomic API.
+- Ensure the hook name starts with `greg.`.
@@ -1,27 +1,25 @@
-- gregCore Lua Example Mod
-
+-- example_mod/main.lua
 function on_init()
-    greg.log_info("Lua Example Mod geladen!")
-    greg.show_notification("Lua Mod Initialisiert")
+    greg.log_info("Lua Example Mod initialized!")
    
-    -- Event abonnieren
-    greg.subscribe_event(100, function(data)
-        greg.log_info("Geld hat sich geändert! Neuer Stand: " .. greg.get_player_money())
+    -- Subscribe to coin changed hook
+    greg.on("greg.PLAYER.CoinChanged", function(payload)
+        local amount = payload.data["Amount"]
+        local total = payload.data["Total"]
+        greg.log_info("Lua received money update: " .. tostring(amount) .. " (Total: " .. tostring(total) .. ")")
+        
+        -- Fire a custom hook back
+        greg.fire("greg.CUSTOM.LuaResponse", {
+            msg = "Lua heard that!",
+            received_total = total
+        })
    end)
 end

 function on_update(dt)
-    -- Wird jeden Frame aufgerufen
-end
-
-function on_event(event_id, data)
-    -- Generischer Event-Handler
-end
-
-function on_scene_loaded(name)
-    greg.log_info("Szene geladen: " .. name)
+    -- Update logic
 end

 function on_shutdown()
-    greg.log_info("Lua Mod wird beendet.")
+    greg.log_info("Lua Example Mod shutdown.")
 end