Obrazki przedmiotów ox_inventory z CDN

Każdy przedmiot w ox_inventory ma swój PNG w ox_inventory/web/images. Na serwerze z kilkuset własnymi itemami ten folder spokojnie urasta do kilkudziesięciu megabajtów, a cały jest częścią resource’a, który każdy gracz musi pobrać, zanim zacznie grać. W tym poradniku przenosimy obrazki na CDN: jeden upload zipa, jedna linijka w server.cfg i inventory ładuje obrazki z cdn.fivedock.dev.

Po co wyciągać obrazki z resource’a

fxmanifest.lua ox_inventory ma w files wpis web/images/*.png, więc każdy obrazek jest plikiem resource’a: serwer wysyła go każdemu klientowi, a klient trzyma go w cache FiveM. To kosztuje:

• Dłuższe wejście na serwer. Nowy gracz przed spawnem pobiera cały folder, łącznie z obrazkami itemów, których nigdy nie weźmie do ręki.
• Każda zmiana to kolejne pobieranie. FiveM cache’uje pliki resource’ów po hashu, więc niezmieniony obrazek nie jest pobierany drugi raz. Ale każdy dodany albo podmieniony obrazek to kolejny plik, który każdy gracz ściąga przy następnym wejściu.
• Nowe obrazki wymagają restartu. Nowy plik w resource trafia do graczy dopiero po restarcie ox_inventory, a na żywym serwerze to ostatni resource, który chcesz restartować.

Z CDN obrazki w ogóle nie są częścią resource’a. Strona inventory prosi o obrazek dopiero wtedy, gdy ma pokazać dany item, i trzyma go w cache HTTP na następny raz. Gracz, który nigdy nie otworzy sklepu z bronią, nigdy nie pobierze obrazków broni.

Skąd ox_inventory bierze obrazek

ox_inventory czyta replikowany convar inventory:imagepath i skleja z niego link do obrazka: <imagepath>/<nazwa itemu>.png. Domyślnie wskazuje na sam resource:

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

Wystarczy więc folder w sieci, w którym każdy obrazek nazywa się dokładnie tak jak item. Dwa szczegóły ze źródeł ox_inventory, które warto znać:

• Rozszerzenie to zawsze .png. Trzymaj obrazki jako PNG nazwane jak item: burger.png, a nie Burger.PNG czy burger.webp.
• Własne client.image itemu dalej wygrywa. Pełny URL jest używany bez zmian, a sama nazwa pliku, np. burger_deluxe.png, jest szukana pod imagepath, więc przenosi się na CDN razem z resztą.

Wgraj obrazki

W FiveDock plik wgrany z kluczem dostaje link, który się nie zmienia: https://cdn.fivedock.dev/o/<your-workspace>/<key>. Wgraj obrazki tak, żeby burger.png dostał klucz items/burger.png, a imagepath to po prostu …/items. Slug środowiska to krótka nazwa widoczna w panelu, a przy okazji nazwa twojego bucketu S3.

Z panelu

1. Spakuj zawartość folderu, a nie sam folder: na Windowsie otwórz ox_inventory/web/images, zaznacz wszystkie pliki Ctrl+A, kliknij prawym i wybierz Wyślij do → Folder skompresowany (zip) albo uruchom zip -r ../images.zip . w ox_inventory/web/images.
2. W panelu otwórz Pliki, utwórz folder items i wejdź do niego.
3. Kliknij Wyślij plik i upuść zipa. Opcja Zachowaj nazwy plików z archiwów .zip i .rar jest domyślnie włączona; zostaw tak.

FiveDock rozpakowuje archiwum i zapisuje każdy obrazek jako osobny plik. Foldery z archiwum zostają zachowane, dlatego pakujesz obrazki, a nie folder images: burger.png staje się items/burger.png, a nie items/images/burger.png. Wszystko, co nie jest obsługiwanym obrazkiem, jak zabłąkany readme.txt, zostaje pominięte i pokazane w wyniku.

Przez API

To samo jednym requestem, z tokenem API (fd_live_…, tworzysz go na stronie Tokeny) ze scope’em 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 to stały link z kluczem, a fileUrl to link do konkretnego uploadu, który dostaje każdy plik. Jedno archiwum mieści do 5000 plików, czyli prawie każdą listę itemów. Jeśli twoja jest większa, wgraj ją w dwóch archiwach albo użyj rclone.

Przez rclone (S3)

Jeśli trzymasz serwer w Gicie albo wdrażasz skryptami, najwygodniejszy jest endpoint S3. Skonfiguruj remote rclone o nazwie fivedock tak, jak w dokumentacji wgrywania, a potem:

# 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

Obiekty wgrane przez S3 to też pliki z kluczem, więc dostają takie same stałe linki.

Przestaw ox_inventory na CDN

Dopisz convar do server.cfg, nad linijką, która startuje ox_inventory:

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

ensure ox_inventory

• Użyj setr, a nie set: UI inventory działa po stronie klienta, a do klientów trafiają tylko convary ustawione przez setr.
• Bez ukośnika na końcu, ox_inventory dokłada go sam.
• ox_inventory czyta convar przy starcie, więc zrestartuj go (albo serwer) raz.

Przed restartem otwórz jeden obrazek w przeglądarce i sprawdź link, np. https://cdn.fivedock.dev/o/<your-workspace>/items/burger.png.

Usuń obrazki z resource’a

Wejdź na serwer, otwórz ekwipunek i jeden czy dwa sklepy i sprawdź, czy obrazki się ładują. Jeśli tak, przenieś pliki PNG z ox_inventory/web/images gdzie indziej: ten folder jest teraz źródłem do uploadów, a nie częścią serwera. Resource robi się lżejszy, a nowi gracze przestają pobierać obrazki, których mogą nigdy nie zobaczyć.

Przy kolejnej aktualizacji ox_inventory nie kopiuj web/images albo wyczyść go ponownie po aktualizacji.

Nowe i podmienione obrazki

Tu linki z kluczem pokazują, ile są warte. Żeby dodać obrazek nowego itemu albo poprawić stary, wgraj PNG z kluczem, który ma mieć: Wyślij plik w folderze items w panelu z włączoną opcją Zachowaj nazwy plików (stałe linki) albo przez API:

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

Jeśli items/burger.png już istnieje, upload podmienia go pod tym samym linkiem; stara wersja jest trzymana jeszcze 7 dni, zanim zostanie usunięta. Linki z kluczem są cache’owane przez 5 minut, a potem rewalidowane, więc gracze zobaczą nowy obrazek w ciągu mniej więcej pięciu minut. Bez restartu i bez niczego nowego do pobrania przy wejściu.

Gdy obrazek się nie pokazuje

• Jeden item ma pusty obrazek. Nazwa pliku musi dokładnie pasować do nazwy itemu, łącznie z wielkością liter: WEAPON_PISTOL.png dla WEAPON_PISTOL. Klucze tworzone z nazw plików zamieniają spacje na -, a inne nietypowe znaki na _, więc obrazek my item.png skończy jako my-item.png.
• Wszystkie obrazki są puste. Otwórz w przeglądarce imagepath z dopisanym /burger.png. 404 zwykle oznacza zły folder (items/images/burger.png zamiast items/burger.png) albo zły slug środowiska. Sprawdź też, czy użyłeś setr.
• Po podmianie dalej widać stary obrazek. Daj mu pięć minut; gracze trzymają poprzednią kopię, dopóki nie wygaśnie ich cache.
• Item ignoruje CDN. Pewnie ma w client.image pełny URL. Usuń go albo skieruj na CDN.

Częste pytania

Skąd ox_inventory ładuje obrazki przedmiotów?

Z replikowanego convara inventory:imagepath, który domyślnie wskazuje na nui://ox_inventory/web/images, czyli folder web/images w samym resource. Dla każdego itemu ox_inventory skleja link <imagepath>/<nazwa itemu>.png. Własne client.image itemu ma pierwszeństwo: pełny URL jest używany bez zmian, a sama nazwa pliku jest szukana pod imagepath.

Jak zmienić ścieżkę obrazków w ox_inventory?

Dopisz setr inventory:imagepath "https://cdn.fivedock.dev/o/<your-workspace>/items" do server.cfg nad ensure ox_inventory, bez ukośnika na końcu, i raz zrestartuj ox_inventory. Musi to być setr, bo UI ekwipunku działa po stronie klienta, a do klientów trafiają tylko convary z setr. Każdy obrazek musi wtedy leżeć pod tym adresem i nazywać się dokładnie jak item, z rozszerzeniem .png.

Czemu nie widać obrazków przedmiotów w ox_inventory?

Najczęściej nazwa pliku nie zgadza się dokładnie z nazwą itemu, łącznie z wielkością liter, albo plik nie jest .png. Jeśli nie ma żadnego obrazka, otwórz w przeglądarce imagepath z dopisanym /burger.png: 404 znaczy, że w ścieżce jest zły folder albo zły slug środowiska. Sprawdź też, czy convar ustawiłeś przez setr, a nie set.

Czy ox_inventory obsługuje obrazki WebP albo JPG?

Tylko dla pojedynczych itemów. Imagepath zawsze dokleja do nazwy itemu .png, więc leżący obok burger.webp nigdy nie zostanie pobrany. Ustaw w client.image itemu burger.webp, który będzie szukany pod imagepath, albo pełny URL, a strona NUI ekwipunku wczyta go jak każda przeglądarka.

Czy po zmianie obrazka trzeba restartować ox_inventory?

Nie, jeśli obrazki są na CDN. Wgraj nowy PNG pod ten sam klucz, np. items/burger.png, a gracze zobaczą go w ciągu mniej więcej pięciu minut, gdy wygaśnie ich kopia w cache. Obrazki w web/images trafiają do graczy dopiero po restarcie ox_inventory.