Hooks

Hooks sind eine Möglichkeit, das Verhalten des Inventarsystems zu verändern. Sie werden auf dem Server registriert und können z.B. genutzt werden, um Spieler daran zu hindern, Items in ein bestimmtes Inventar zu verschieben. Einige Beispiele für Hooks findest du im Ordner jaksam_inventory/_hooks.

Best Practices

Filter nutzen

Verwende immer passende Filter, um unnötige Hook-Ausführungen zu vermeiden

Frühe Rückgaben

Nutze frühe returns, um Hooks zu verlassen, wenn Bedingungen nicht erfüllt sind

Performance

Halte die Hook-Logik schlank, um die Inventar-Performance nicht zu beeinträchtigen

Anwendungsbeispiele

Verhindern, dass Spieler Items mit dem Metadaten-Feld sole_owner stehlen (z.B. VIP-Items)
Verhindern, dass Spieler Polizeiwaffen in ihr persönliches Inventar verschieben
Nur einen Rucksack pro Spieler-Inventar erlauben
Items craften, indem ein bestimmtes Item auf ein anderes gezogen wird (z.B. Brot auf Fleisch ziehen ergibt ein Sandwich)
Item-Nutzung blockieren, wenn der Spieler gefesselt ist oder sich in bestimmten Zonen befindet
Item-Nutzungsstatistiken und Erfolge erfassen
Die Nutzung bestimmter Items in Fahrzeugen verhindern
Neuen Spieler-Inventaren bei der Erstellung Starter-Items hinzufügen
Mülltonnen oder Stashes bei der Erstellung mit zufälligen Items vorbefüllen

API-Funktionen

Einen Hook registrieren

exports['jaksam_inventory']:registerHook(eventName, callback, options, priority)

Parameter

Name	Datentyp	Beschreibung
`eventName`	string	Der Name des Hook-Events, auf das gehört werden soll (siehe Verfügbare Hook-Events unten)
`callback`	function	Die Funktion, die beim Auslösen des Hooks ausgeführt wird
`options`	table	Filter und Konfigurationsoptionen (siehe Options-Parameter unten)
`priority`	number	Ausführungspriorität (höhere Zahlen werden zuerst ausgeführt, Standard: 0)

Rückgabewert

Name	Datentyp	Beschreibung
`hookId`	string	Eindeutige ID des registrierten Hooks (wird zum Deregistrieren des Hooks benötigt)

Einen Hook deregistrieren

exports['jaksam_inventory']:unregisterHook(hookId)

Parameter

Name	Datentyp	Beschreibung
`hookId`	string	Die eindeutige ID, die beim Registrieren des Hooks zurückgegeben wurde

Alle Hooks einer Resource deregistrieren

exports['jaksam_inventory']:unregisterResourceHooks(resourceName)

Parameter

Name	Datentyp	Beschreibung
`resourceName`	string	Name der Resource, deren Hooks alle deregistriert werden sollen

Options-Parameter

Der Options-Parameter akzeptiert eine Table mit Filtern zur Performance-Optimierung.

Allgemein (alle Events)
Inventar-Filter
Übertragungs-Filter

    local options = {
        -- Debug: Bei Auslösung des Hooks in die Konsole ausgeben
        print = true,

        -- Nur für bestimmte Items auslösen
        itemNameFilter = {
            bread = true,
            weapon_pistol = true
        },

        -- Nur für bestimmte Item-Typen auslösen
        itemTypeFilter = {
            weapon = true,
            currency = true
        }
    }

Für onItemAdded, onItemRemoved, onInventoryCreated, onPreOpenInventory, onOmnipackTransaction:

    local options = {
        -- Nach Inventartyp filtern (empfohlen)
        inventoryTypeFilter = {
            player = true,
            stash = true
        },

        -- Nach bestimmten Inventarmustern filtern (fortgeschritten)
        inventoryFilter = {
            "player:.*",      -- Alle Spieler
            "stash_police"    -- Bestimmter Stash
        }
    }

Nur für onItemTransferred:

    local options = {
        -- Quell-Inventar nach Typ filtern
        inventoryFromTypeFilter = { player = true },

        -- Quell-Inventar nach Namensmuster filtern
        inventoryFromFilter = {
            "player:.*",      -- Alle Spieler
            "vehicle:123"     -- Bestimmtes Fahrzeug
        },

        -- Ziel-Inventar nach Typ filtern
        inventoryToTypeFilter = { stash = true },

        -- Ziel-Inventar nach Namensmuster filtern
        inventoryToFilter = {
            "stash_police",   -- Bestimmter Stash
            "container:.*"    -- Alle Container
        },

        -- Nur Bewegungen innerhalb desselben Inventars (Ziehen im gleichen Inventar)
        intraInventoryOnly = true
    }

Verfügbare Hook-Events

Event	Beschreibung
Item added	Wird ausgelöst, wenn ein Item zu einem Inventar hinzugefügt wird
Item removed	Wird ausgelöst, wenn ein Item aus einem Inventar entfernt wird
Item transferred	Wird ausgelöst, wenn ein Item zwischen Inventaren übertragen wird
Omnipack transaction	Wird ausgelöst, wenn ein Admin über das Admin-Inventar ein Item erstellt oder zerstört
Pre use item	Wird vor der Nutzung eines Items ausgelöst, kann die Nutzung abbrechen
Post use item	Wird nach der Nutzung eines Items ausgelöst, nur zur Benachrichtigung
Inventory created	Wird ausgelöst, wenn ein neues Inventar erstellt wird
Pre open inventory	Wird ausgelöst, bevor ein sekundäres Inventar geöffnet wird, kann das Öffnen verhindern

Hook-Verhalten

Priorität

Höhere Zahlen werden zuerst ausgeführt (Standard: 0)

Rückgabewerte

return nil oder return true: die Aktion wird fortgesetzt.return false, "message", "notifyType": verhindert die Aktion und stoppt die weitere Hook-Ausführung. Die Parameter message und notifyType sind optional (notifyType kann "error", "success", "info" sein)

Ausnahme - onPreOpenInventory: die Nachricht wird dem Spieler nicht angezeigt, weil das Vorladen sie wiederholen würde. Rufe notifyPlayer innerhalb des Hooks auf, wenn du dem Spieler den Grund mitteilen möchtest.

ox_inventory-Kompatibilität

Wenn die ox_inventory-Kompatibilitätsressource installiert ist, wird exports.ox_inventory:registerHook(...) in die obigen nativen Hooks übersetzt, sodass ox_inventory-Scripts ohne Änderungen funktionieren. Payloads werden in das ox-Format umgewandelt, und auch die ox-Optionsnamen (itemFilter, typeFilter, inventoryFilter, print) werden übersetzt.

ox_inventory-Hook	Unterstützt	Verwendeter nativer Hook
`createItem`	Ja	`onItemAdded`
`swapItems`	Ja	`onItemTransferred`
`openInventory`	Ja	`onPreOpenInventory`
`usingItem`	Ja	`onPreUseItem`
`buyItem` / `openShop`	Nein	noch keine Shop-Hooks
`craftItem`	Nein	noch keine Crafting-Hooks

Das Registrieren eines nicht unterstützten Hooks gibt eine Warnung aus und liefert nil zurück, statt einen Fehler zu werfen. Drei Unterschiede, die bei der Migration zu beachten sind:

Ein ox-Hook kann nur erlauben oder blockieren; er kann keine eigene Nachricht oder Benachrichtigungsart liefern. Nutze dafür die nativen Hooks
openInventory erbt die Anforderung der Zustandslosigkeit, die unter onPreOpenInventory beschrieben ist
Spieler-Inventare werden unterschiedlich identifiziert. ox-Hooks erhalten die Server-ID des Spielers als number (inventoryId = 4), passend zu ox_inventory. Native Hooks erhalten den Charakter-Identifier von jaksam als string (inventoryId = "char1:35030084..."). Jeder andere Inventartyp verwendet in beiden Fällen dieselbe string-ID

General

Inventory

Jobs Creator

Drugs Creator

Doors Creator

Missions Creator

Blips Creator

Farming Creator

Shops Creator

Robberies Creator

Vehicles Keys

Dealerships Creator

Races Creator

Trackers Creator

Easy Allowlist

Billing UI

Luxury Clothes Theft

Best Practices

Filter nutzen

Frühe Rückgaben

Performance

Anwendungsbeispiele

API-Funktionen

Einen Hook registrieren

Parameter

Rückgabewert

Einen Hook deregistrieren

Parameter

Alle Hooks einer Resource deregistrieren

Parameter

Options-Parameter

Verfügbare Hook-Events

Hook-Verhalten

Priorität

Rückgabewerte

ox_inventory-Kompatibilität

​Best Practices

Filter nutzen

Frühe Rückgaben

Performance

​Anwendungsbeispiele

​API-Funktionen

​Einen Hook registrieren

​Parameter

​Rückgabewert

​Einen Hook deregistrieren

​Parameter

​Alle Hooks einer Resource deregistrieren

​Parameter

​Options-Parameter

​Verfügbare Hook-Events

​Hook-Verhalten

Priorität

Rückgabewerte

​ox_inventory-Kompatibilität

Best Practices

Anwendungsbeispiele

API-Funktionen

Einen Hook registrieren

Parameter

Rückgabewert

Einen Hook deregistrieren

Parameter

Alle Hooks einer Resource deregistrieren

Parameter

Options-Parameter

Verfügbare Hook-Events

Hook-Verhalten

ox_inventory-Kompatibilität