Servir las imágenes de items de ox_inventory desde un CDN

Cada item de ox_inventory tiene un PNG en ox_inventory/web/images. En un servidor con unos cientos de items propios, esa carpeta crece fácilmente hasta decenas de megas, y todo forma parte de un resource que cada jugador descarga antes de poder jugar. Esta guía mueve las imágenes a un CDN: una subida de zip, una línea en server.cfg, y el inventario carga sus imágenes desde cdn.fivedock.dev.

Por qué sacar las imágenes del resource

El fxmanifest.lua de ox_inventory lista web/images/*.png en files, lo que convierte cada imagen en un archivo del resource: el servidor la envía a cada cliente y el cliente la guarda en su caché de FiveM. Eso tiene algunos costes:

• Un jugador nuevo descarga la carpeta entera antes de aparecer, incluidas imágenes de items que nunca tendrá en la mano, así que entrar tarda más.
• FiveM cachea los archivos del resource por hash, así que una imagen sin cambios no se descarga dos veces. Pero cada imagen que añades o reemplazas es un archivo más que cada jugador descarga en su siguiente entrada.
• Un archivo nuevo en el resource solo llega a los jugadores tras reiniciar ox_inventory, y en un servidor en producción es el resource que menos quieres reiniciar.

Con un CDN, las imágenes ya no forman parte del resource. La página de navegador del inventario pide una imagen solo cuando tiene que mostrar ese item, y la guarda en su caché HTTP para la próxima vez. Un jugador que nunca abre la armería nunca descarga las imágenes de armas.

Cómo encuentra ox_inventory una imagen

ox_inventory lee el convar replicado inventory:imagepath y construye cada enlace de imagen como <imagepath>/<item name>.png. El valor por defecto apunta al propio resource:

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

Solo necesita, por tanto, una carpeta en la web donde cada imagen se llame exactamente como su item. Dos detalles del código fuente de ox_inventory:

• La extensión es siempre .png. Deja las imágenes como archivos PNG con el nombre del item: burger.png, no Burger.PNG ni burger.webp.
• El client.image propio de un item sigue ganando. Una URL completa ahí se usa tal cual; un nombre de archivo suelto como burger_deluxe.png se busca bajo el imagepath, así que se mueve al CDN con todo lo demás.

Sube las imágenes

En FiveDock, un archivo subido con clave recibe un enlace que nunca cambia: https://cdn.fivedock.dev/o/<your-workspace>/<key>. Sube las imágenes de modo que burger.png tenga la clave items/burger.png y el imagepath sea …/items. El slug de tu organización es el nombre corto que muestra el panel, y también es el nombre de tu bucket S3.

Desde el panel

1. Comprime el contenido de la carpeta, no la carpeta en sí: en Windows, abre ox_inventory/web/images, selecciona todos los archivos con Ctrl+A, haz clic derecho y elige Enviar a → Carpeta comprimida (en zip), o ejecuta zip -r ../images.zip . dentro de ox_inventory/web/images.
2. En el panel, abre Archivos, crea una carpeta llamada items y ábrela.
3. Pulsa Subir un archivo y suelta el zip. Mantener nombres de archivo viene activado por defecto para los archivos comprimidos; déjalo activado.

FiveDock descomprime el archivo y guarda cada imagen como un archivo propio. Las carpetas dentro del archivo se conservan, por eso comprimes las imágenes y no la carpeta images: burger.png pasa a ser items/burger.png, no items/images/burger.png. Todo lo que no sea una imagen aceptada, como un readme.txt perdido, se omite y aparece en el resultado.

Por la API

Lo mismo en una sola petición, con un token de API (fd_live_…, creado en la página Tokens) con el 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 es el enlace estable con clave; fileUrl es el enlace por subida que además recibe todo archivo. Un archivo comprimido puede contener hasta 5000 archivos, lo que cubre casi cualquier lista de items. Si la tuya es mayor, súbela en dos archivos comprimidos o usa rclone.

Con rclone (S3)

Si guardas tu servidor en Git o despliegas con scripts, el endpoint S3 es la vía más cómoda. Configura un remote de rclone llamado fivedock como se muestra en la documentación de subidas y luego:

# 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

Los objetos que subes por S3 también son archivos con clave, así que tienen los mismos enlaces estables.

Apunta ox_inventory al CDN

Añade el convar a server.cfg, encima de la línea que arranca ox_inventory:

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

ensure ox_inventory

• Usa setr, no set: la UI del inventario se ejecuta en el cliente, y solo los convars setr se replican a los clientes.
• Sin barra final, ox_inventory la añade.
• ox_inventory lee el convar al arrancar, así que reinícialo (o reinicia el servidor) una vez.

Antes de reiniciar, abre una imagen en el navegador para comprobar el enlace, por ejemplo https://cdn.fivedock.dev/o/<your-workspace>/items/burger.png.

Saca las imágenes del resource

Entra al servidor, abre tu inventario y una o dos tiendas, y comprueba que las imágenes cargan. Cuando lo hagan, saca los archivos PNG de ox_inventory/web/images y guárdalos en otro sitio: esa carpeta es ahora la fuente de tus subidas, no parte del servidor.

Cuando actualices ox_inventory más adelante, deja web/images fuera de la copia, o vacíala otra vez después.

Añadir y reemplazar imágenes más adelante

Para añadir la imagen de un item nuevo, o corregir una antigua, sube el PNG con la clave que debe tener: Subir un archivo en la carpeta items del panel con Mantener nombres de archivo activado, o la API:

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

Si items/burger.png ya existe, la subida lo reemplaza detrás del mismo enlace; la versión anterior se conserva 7 días antes de purgarse. Los enlaces con clave se cachean 5 minutos y luego se revalidan, así que los jugadores ven la imagen nueva en unos cinco minutos, sin reiniciar y sin nada nuevo que descargar al entrar.

Si una imagen no se muestra

• Un item tiene la imagen rota. El nombre del archivo debe coincidir exactamente con el nombre del item, mayúsculas incluidas: WEAPON_PISTOL.png para WEAPON_PISTOL. Las claves construidas a partir de nombres de archivo convierten los espacios en - y otros caracteres raros en _, así que una imagen llamada my item.png acaba como my-item.png.
• Todas las imágenes están rotas. Abre el imagepath más /burger.png en un navegador. Un 404 suele significar que la carpeta no es la correcta (items/images/burger.png en lugar de items/burger.png) o que el slug de la organización está mal. Comprueba también que usaste setr.
• La imagen antigua sigue ahí tras reemplazarla. Dale cinco minutos; los jugadores conservan la copia anterior hasta que caduca su caché.
• Un item ignora el CDN. Probablemente define client.image con una URL completa. Quítalo, o haz que apunte al CDN.

Preguntas frecuentes

¿De dónde carga ox_inventory las imágenes de los items?

Del convar replicado inventory:imagepath, que por defecto es nui://ox_inventory/web/images, la carpeta web/images dentro del resource. Para cada item, ox_inventory construye el enlace <imagepath>/<item name>.png. El client.image propio de un item lo sobrescribe: una URL completa se usa tal cual, y un nombre de archivo suelto se busca bajo el imagepath.

¿Cómo cambio el imagepath de ox_inventory?

Añade setr inventory:imagepath "https://cdn.fivedock.dev/o/<your-workspace>/items" a server.cfg encima de ensure ox_inventory, sin barra al final, y reinicia ox_inventory una vez. Tiene que ser setr, porque la UI del inventario se ejecuta en el cliente y solo los convars setr llegan a los clientes. Cada imagen debe estar entonces en esa dirección, con el nombre exacto de su item y la extensión .png.

¿Por qué no se muestran las imágenes de mis items de ox_inventory?

Lo habitual es que el nombre del archivo no coincida exactamente con el del item, mayúsculas y minúsculas incluidas, o que el archivo no sea un .png. Si faltan todas las imágenes, abre el imagepath más /burger.png en un navegador: un 404 significa que la carpeta o el slug de la organización en la ruta están mal. Comprueba también que el convar se definió con setr y no con set.

¿Puede ox_inventory usar imágenes de items en WebP o JPG?

Solo item por item. La búsqueda por imagepath siempre añade .png al nombre del item, así que un burger.webp al lado nunca se pide. Define el client.image del item como burger.webp, que se busca bajo el imagepath, o como una URL completa, y la página NUI del inventario lo carga como lo haría cualquier navegador.

¿Tengo que reiniciar ox_inventory para cambiar la imagen de un item?

No, cuando las imágenes están en un CDN. Sube el PNG nuevo a la misma clave, como items/burger.png, y los jugadores lo ven en unos cinco minutos, cuando caduca su copia en caché. Las imágenes dentro de web/images solo llegan a los jugadores tras reiniciar ox_inventory.