ox_inventory Item-Bilder über ein CDN ausliefern

Jedes Item in ox_inventory hat ein PNG in ox_inventory/web/images. Auf einem Server mit ein paar hundert eigenen Items wächst dieser Ordner schnell auf mehrere zehn Megabyte, und alles davon gehört zu einer Resource, die jeder Spieler herunterlädt, bevor er spielen kann. Diese Anleitung verlegt die Bilder auf ein CDN: ein Zip-Upload, eine Zeile in server.cfg, und das Inventar lädt seine Bilder stattdessen von cdn.fivedock.dev.

Warum die Bilder aus der Resource raus sollten

In der fxmanifest.lua von ox_inventory steht web/images/*.png unter files. Dadurch ist jedes Bild eine Resource-Datei: Der Server schickt sie an jeden Client, und der Client legt sie in seinem FiveM-Cache ab. Das hat ein paar Nachteile:

• Ein neuer Spieler lädt vor dem Spawnen den ganzen Ordner herunter, auch Bilder von Items, die er nie in der Hand haben wird. Das Joinen dauert also länger.
• FiveM cached Resource-Dateien nach Hash, ein unverändertes Bild wird also nicht zweimal geholt. Aber jedes Bild, das du hinzufügst oder ersetzt, ist eine Datei mehr, die jeder Spieler beim nächsten Join herunterlädt.
• Eine neue Datei in der Resource erreicht die Spieler erst nach einem Neustart von ox_inventory, und auf einem Live-Server ist das die Resource, die du am wenigsten neu starten willst.

Mit einem CDN gehören die Bilder gar nicht mehr zur Resource. Die Browser-Seite des Inventars fragt ein Bild erst an, wenn sie das Item zeigen muss, und behält es danach in ihrem HTTP-Cache. Ein Spieler, der nie den Waffenladen öffnet, lädt die Waffenbilder nie herunter.

Wie ox_inventory ein Bild findet

ox_inventory liest den replizierten Convar inventory:imagepath und baut jeden Bildlink als <imagepath>/<item name>.png. Der Standard zeigt in die Resource selbst:

default  nui://ox_inventory/web/images/burger.png
CDN      https://cdn.fivedock.dev/o/<your-workspace>/items/burger.png

Es braucht also nur einen Ordner im Web, in dem jedes Bild genau so heißt wie sein Item. Zwei Details aus dem Quellcode von ox_inventory:

• Die Endung ist immer .png. Lass die Bilder PNG-Dateien bleiben, benannt nach dem Item: burger.png, nicht Burger.PNG oder burger.webp.
• Das client.image eines Items hat weiterhin Vorrang. Eine vollständige URL dort wird unverändert benutzt, ein bloßer Dateiname wie burger_deluxe.png wird unter dem Imagepath gesucht und zieht damit mit allem anderen aufs CDN um.

Die Bilder hochladen

Bei FiveDock bekommt eine Datei, die mit Key hochgeladen wird, einen Link, der sich nie ändert: https://cdn.fivedock.dev/o/<your-workspace>/<key>. Lade die Bilder so hoch, dass burger.png den Key items/burger.png bekommt, dann ist der Imagepath …/items. Der Slug deiner Organisation ist der im Panel angezeigte Kurzname und zugleich der Name deines S3-Buckets.

Über das Panel

1. Zippe den Inhalt des Ordners, nicht den Ordner selbst: Öffne unter Windows ox_inventory/web/images, markiere mit Strg+A alle Dateien, klicke mit rechts und wähle Senden an → ZIP-komprimierter Ordner, oder führe zip -r ../images.zip . in ox_inventory/web/images aus.
2. Öffne im Panel Dateien, lege einen Ordner namens items an und öffne ihn.
3. Klicke auf Datei hochladen und zieh das Zip hinein. Dateinamen behalten ist bei Archiven standardmäßig an; lass es an.

FiveDock entpackt das Archiv und speichert jedes Bild als eigene Datei. Ordner im Archiv bleiben erhalten, deshalb zippst du die Bilder und nicht den Ordner images: Aus burger.png wird items/burger.png, nicht items/images/burger.png. Alles, was kein akzeptiertes Bild ist, etwa eine verirrte readme.txt, wird übersprungen und im Ergebnis aufgelistet.

Über die API

Dasselbe in einem Request, mit einem API-Token (fd_live_…, erstellt auf der Seite Tokens) mit dem Scope files:write:

cd ox_inventory/web/images
zip -r ../images.zip .

curl -X POST https://api.fivedock.dev/api/v3/file/archive \
  -H "Authorization: Bearer fd_live_…" \
  -F "file=@../images.zip" \
  -F "path=items"

{
  "status": "ok",
  "data": {
    "uploaded": [
      {
        "key": "items/burger.png",
        "url": "https://cdn.fivedock.dev/o/my-city/items/burger.png",
        "fileUrl": "https://cdn.fivedock.dev/f/…png",
        "filename": "burger.png",
        "path": "/items",
        "size": 18233,
        "mime_type": "image/png",
        "deduplicated": false
      }
    ],
    "skipped": [{ "name": "readme.txt", "reason": "unsupported_type" }]
  }
}

url ist der stabile Link mit Key, fileUrl der Link pro Upload, den jede Datei zusätzlich bekommt. Ein Archiv kann bis zu 5.000 Dateien enthalten, was fast jede Item-Liste abdeckt. Ist deine größer, lade sie in zwei Archiven hoch oder nimm rclone.

Mit rclone (S3)

Wenn du deinen Server in Git hältst oder mit Scripts deployst, ist der S3-Endpoint der bequemste Weg. Richte einen rclone-Remote namens fivedock ein, wie in der Upload-Doku beschrieben, dann:

# my-city = your workspace slug (it is also your S3 bucket name)
rclone sync ./ox_inventory/web/images fivedock:my-city/items --dry-run
rclone sync ./ox_inventory/web/images fivedock:my-city/items

Objekte, die du über S3 ablegst, sind ebenfalls Dateien mit Key und bekommen dieselben stabilen Links.

ox_inventory aufs CDN zeigen lassen

Füge den Convar in server.cfg ein, über der Zeile, die ox_inventory startet:

setr inventory:imagepath "https://cdn.fivedock.dev/o/<your-workspace>/items"

ensure ox_inventory

• Nimm setr, nicht set: Das Inventar-UI läuft auf dem Client, und nur setr-Convars werden an Clients repliziert.
• Kein Slash am Ende, den ergänzt ox_inventory selbst.
• ox_inventory liest den Convar beim Start, starte es (oder den Server) also einmal neu.

Öffne vor dem Neustart ein Bild im Browser, um den Link zu prüfen, zum Beispiel https://cdn.fivedock.dev/o/<your-workspace>/items/burger.png.

Die Bilder aus der Resource nehmen

Joine dem Server, öffne dein Inventar und ein, zwei Shops und prüfe, ob die Bilder laden. Sobald das klappt, verschiebe die PNG-Dateien aus ox_inventory/web/images und bewahre sie woanders auf: Dieser Ordner ist jetzt die Quelle für deine Uploads und gehört nicht mehr zum Server.

Wenn du ox_inventory später aktualisierst, lass web/images beim Kopieren weg oder leere den Ordner danach wieder.

Bilder später hinzufügen und ersetzen

Um ein Bild für ein neues Item hinzuzufügen oder ein altes zu korrigieren, lade das PNG mit dem Key hoch, den es haben soll: Datei hochladen im Ordner items des Panels mit Dateinamen behalten an, oder per API:

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "key=items/burger.png"

Existiert items/burger.png schon, ersetzt der Upload die Datei hinter demselben Link; die alte Version bleibt 7 Tage erhalten, bevor sie gelöscht wird. Links mit Key werden 5 Minuten gecacht und danach neu geprüft, die Spieler sehen das neue Bild also nach etwa fünf Minuten, ohne Neustart und ohne etwas Neues beim Join herunterzuladen.

Wenn ein Bild nicht erscheint

• Ein Item hat ein kaputtes Bild. Der Dateiname muss genau zum Item-Namen passen, auch in der Groß- und Kleinschreibung: WEAPON_PISTOL.png für WEAPON_PISTOL. Keys aus Dateinamen machen aus Leerzeichen - und aus anderen ungewöhnlichen Zeichen _, ein Bild namens my item.png landet also als my-item.png.
• Alle Bilder sind kaputt. Öffne den Imagepath plus /burger.png im Browser. Ein 404 heißt meistens, dass der Ordner nicht stimmt (items/images/burger.png statt items/burger.png) oder der Slug der Organisation falsch ist. Prüfe außerdem, ob du setr benutzt hast.
• Nach dem Ersetzen ist noch das alte Bild da. Gib ihm fünf Minuten; Spieler behalten die vorherige Kopie, bis ihr Cache abläuft.
• Ein Item ignoriert das CDN. Wahrscheinlich setzt es client.image auf eine vollständige URL. Entferne das oder lass es aufs CDN zeigen.

Häufige Fragen

Woher lädt ox_inventory die Item-Bilder?

Aus dem replizierten Convar inventory:imagepath, der standardmäßig auf nui://ox_inventory/web/images zeigt, den Ordner web/images in der Resource. Für jedes Item baut ox_inventory den Link <imagepath>/<item name>.png. Das client.image eines Items überschreibt das: Eine vollständige URL wird unverändert benutzt, ein bloßer Dateiname wird unter dem Imagepath gesucht.

Wie ändere ich den Imagepath in ox_inventory?

Füge setr inventory:imagepath "https://cdn.fivedock.dev/o/<your-workspace>/items" in server.cfg über ensure ox_inventory ein, ohne Slash am Ende, und starte ox_inventory einmal neu. Es muss setr sein, weil das Inventar-UI auf dem Client läuft und nur setr-Convars die Clients erreichen. Jedes Bild muss dann unter dieser Adresse liegen, benannt wie sein Item, mit der Endung .png.

Warum werden meine ox_inventory-Item-Bilder nicht angezeigt?

Meistens passt der Dateiname nicht genau zum Item-Namen, auch in Groß- und Kleinschreibung, oder die Datei ist kein .png. Fehlen alle Bilder, öffne den Imagepath plus /burger.png im Browser: Ein 404 heißt, dass der Ordner oder der Slug der Organisation im Pfad falsch ist. Prüfe auch, ob der Convar mit setr gesetzt wurde und nicht mit set.

Kann ox_inventory WebP- oder JPG-Item-Bilder verwenden?

Nur Item für Item. Die Imagepath-Suche hängt immer .png an den Item-Namen an, ein danebenliegendes burger.webp wird also nie angefragt. Setze das client.image des Items auf burger.webp, das unter dem Imagepath gesucht wird, oder auf eine vollständige URL, dann lädt die NUI-Seite des Inventars es wie jeder Browser.

Muss ich ox_inventory neu starten, um ein Item-Bild zu ändern?

Nicht, wenn die Bilder auf einem CDN liegen. Lade das neue PNG auf denselben Key hoch, etwa items/burger.png, und die Spieler sehen es nach etwa fünf Minuten, sobald ihre gecachte Kopie abläuft. Bilder in web/images erreichen die Spieler erst nach einem Neustart von ox_inventory.