Documentación de Admin Give Item

Entrega de ítems y vehículos para administradores

Que hace

santabria-admingiveitem es un panel de administración para entregar ítems, armas y vehículos a los jugadores desde el propio juego, sin escribir comandos ni ir a la base de datos. Se abre con un comando, eliges a quién, buscas con iconos, armas un envío y lo mandas.

Un solo comando: /admin_giveitem abre el panel; ESC lo cierra.
Destinatarios múltiples: busca por nombre, ID o citizenid, marca varios jugadores a la vez o usa "Marcar los de la lista".
Jugadores conectados y desconectados: también encuentra personajes que no están en línea y les entrega el ítem o el vehículo directamente.
Catálogo con iconos: lee el catálogo completo de ox_inventory, con búsqueda por nombre y filtro por categoría. Cada ítem muestra su imagen.
Envío múltiple: carrito de hasta 20 ítems por envío, con cantidad y metadata en JSON opcional.
Vehículos: entrega vehículos directo al garaje elegido, con placa única generada automáticamente. Incluye el catálogo de QBCore.Shared.Vehicles y una lista de vehículos addon que se genera con la herramienta incluida.
Auditoría a Discord (opcional): cada entrega queda registrada en un canal si configuras un webhook.
Registro en pantalla: al enviar, el panel muestra qué se entregó y qué falló.

Requisitos

FXServer reciente y Lua 5.4.
qb-core, ox_lib, ox_inventory y oxmysql (están en las dependencies del fxmanifest.lua).
Vehículos: usa la tabla player_vehicles de QBCore. Para listar garajes usa sbr-garages si está iniciado y, si no, la tabla garage_locations de jg-advancedgarages.
Usa QBCore directamente. No incluye un puente para ESX.

Instalacion

Copia la carpeta santabria-admingiveitem en tu carpeta resources.
Añade ensure santabria-admingiveitem en el server.cfg, después de qb-core, ox_lib, ox_inventory y oxmysql.
(Opcional) Para la auditoría a Discord, añade en el server.cfg: set ov_admin_log_webhook "https://discord.com/api/webhooks/..." con la dirección de tu webhook. Sin esa línea la auditoría queda apagada y todo lo demás funciona igual.
(Opcional) Si usas vehículos addon, genera la lista con herramientas/generar_catalogo_vehiculos.py (ver más abajo).
Reinicia el servidor y escribe /admin_giveitem con una cuenta de administrador.

El recurso viene protegido con Asset Escrow de Cfx.re: se descarga desde tu Portal con la cuenta Cfx del comprador y solo funciona en servidores del comprador. Sin cifrar quedan toda la interfaz html/, la carpeta data/ y la carpeta herramientas/; el código Lua de client y server va cifrado.

Configuracion

No tiene archivo de configuración: funciona directamente después de instalarlo.

Qué	Dónde
Webhook de auditoría	convar `ov_admin_log_webhook` en el `server.cfg`
Vehículos addon	`data/vehiculos_extra.json`
Aspecto del panel	`html/css/style.css` (colores y tipografías)
Textos del panel	`html/index.html` y `html/js/script.js`

Vehículos addon

data/vehiculos_extra.json es la lista de vehículos que no están en QBCore.Shared.Vehicles. Para regenerarla con los vehículos de tu servidor, ejecuta en el servidor:

python3 herramientas/generar_catalogo_vehiculos.py <carpeta resources> data/vehiculos_extra.json

La herramienta lee los archivos vehicles*.meta de todos tus recursos.

Comandos y permisos

Comando	Efecto
`/admin_giveitem`	Abre el panel de entrega.

Puede abrir y usar el panel quien cumpla alguno de estos puntos: tiene el grupo admin o god en QBCore, tiene el permiso ACE command, o es la consola del servidor. Todas las entregas se validan de nuevo en el servidor, no solo al abrir el panel.

Como se usa

Escribe /admin_giveitem.
En Destinatarios, busca al jugador por nombre, ID o citizenid y márcalo. Puedes marcar varios.
En Ítems, busca por nombre o filtra por categoría y añade lo que quieras al carrito. Ajusta la cantidad; la metadata en JSON es opcional.
Para vehículos, abre la pestaña Vehículos, elige el modelo y el garaje de destino y añádelo al envío.
Pulsa Enviar. Verás el resultado de cada línea en el registro y el jugador conectado recibe un aviso con un sonido.
Si activas "Vaciar el envío al terminar", el carrito se limpia solo después de enviar.

Para administradores

Límites: máximo 20 ítems por envío y 100000 unidades por línea. La búsqueda muestra hasta 150 ítems y 120 vehículos por consulta; afina el término para encontrar el resto.
Jugadores desconectados: se entrega por citizenid. Si el jugador se conecta justo en ese momento, el panel pide refrescar la búsqueda.
Vehículos: se crean en player_vehicles con combustible, motor y carrocería al 100 %, en estado guardado en el garaje elegido y con una placa de 8 caracteres que no se repite.
Auditoría: si configuras el webhook, cada entrega de ítems o vehículos se envía al canal con quién entregó, a quién y qué.
Ver errores: la consola del servidor muestra líneas con el prefijo [santabria-admingiveitem].

Preguntas frecuentes

¿Funciona con ESX? No. Usa QBCore y la tabla player_vehicles.

¿Funciona con otro inventario que no sea ox_inventory? No, entrega y lee el catálogo con ox_inventory.

¿Puedo dar ítems a alguien que no está conectado? Sí. Búscalo por nombre o citizenid; los desconectados aparecen en la lista.

No me aparecen los vehículos addon. Genera data/vehiculos_extra.json con la herramienta incluida y reinicia el recurso.

No sale ningún garaje al entregar un vehículo. Debe estar iniciado sbr-garages o existir la tabla garage_locations de jg-advancedgarages con garajes creados.

¿Cómo cambio los colores del panel? Edita html/css/style.css; no está cifrado.

Actualizaciones y soporte

Las versiones nuevas aparecen en tu Portal de Cfx.re y en la tienda. Antes de actualizar, guarda una copia de tu data/vehiculos_extra.json. Soporte: [enlace de soporte].