$ USD
Guía del marco Qbox para FiveM
¿Estás probando un script gratuito?
Los scripts gratuitos son útiles para comprobaciones rápidas. Para servidores de producción, compare los paquetes completos para servidores o los scripts de pago con mantenimiento, teniendo en cuenta el framework y el caso de uso.
Respuesta rápida: Qbox is a modern FiveM framework direction commonly used with the overextended stack, including ox_lib, ox_inventory, and ox_target-style workflows. Before migrating from QBCore, audit resources, exports, database tables, inventory, jobs, and admin tooling.
Última actualización: 25 de junio de 2026
Sobreextendido (Buey) es la base moderna para los servidores FiveM. Esta guía le muestra cómo instalar, configurar y migrar de forma segura a inventario_de_bueyes, biblioteca de buey, objetivo_buey, y oxmysqlObtendrás código copiable y pegable, valores predeterminados definidos y patrones probados para la interfaz de usuario, las interacciones y los datos. Incluye manuales para inventario qb → inventario_ox y mysql-async → oxmysql. Haga una copia de seguridad de su servidor y base de datos antes de realizar cualquier cambio.
TL;DR: ¿Qué componente de Ox para qué?
| Componente | Objetivo | API principales | Uso típico | Ruta de migración | Errores comunes |
|---|---|---|---|---|---|
| inventario_de_bueyes | Inventario y artículos, escondites, tiendas | Agregar artículo, Eliminar elemento, RegistrarseStash, RegistrarseTienda | Artículos de jugador, alijos de trabajos, tiendas de vendedores | inventario qb → inventario_ox | Esquema de elemento incorrecto, invs duplicados en ejecución, faltante asegurar orden |
| biblioteca de buey | Utilidades, interfaz de usuario, ayudantes | añadirComando, registrarContexto/mostrarContexto, diálogo de entrada, barra de progreso, zonas/puntos | Menús, indicaciones, límites de velocidad, lógica de zonas | N / A | Mezcla de bibliotecas de UI, sin esperar devoluciones de llamadas |
| objetivo_buey | Segmentación por interacción | addBoxZone, addSphereZone, agregarEntidad, añadir modelo | Objetivos oculares en accesorios/peatones/zonas | qtarget → ox_target (opcional) | Zonas superpuestas, condiciones de trabajo faltantes |
| oxmysql | Controlador MySQL | consulta, soltero, escalar, insertar, preparar, transacción | Persistencia de bases de datos, tablas de clasificación, auditorías | mysql-async → oxmysql | Consultas no indexadas, concat. de cadena no segura |
Consejo: Empezar con oxmysql y biblioteca de buey, luego migrar inventario y objetivo. Validar cada paso en un servidor de prueba.
Relacionado: https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
Prerrequisitos y línea base
- Artefacto reciente del servidor, Administrador de transacciones, y un marco (QBCore o ESX).
- Node.js no es necesario para Ox, pero su pila NUI (si hay alguna) podría usarlo.
- Orden de inicio de recursos:
oxmysql→biblioteca de buey→inventario_de_bueyes→ el resto. Pon objetivo_buey Temprano entre las bibliotecas de UI/interacción. - Lista de verificación:
- El firewall permite el tráfico de la base de datos; el usuario de la base de datos tiene menos privilegios.
- Establecer convars de producción vs. de desarrollo; habilitar advertencias de consultas lentas en el ensayo.
- Copias de seguridad de configuraciones de bases de datos y recursos.
Relacionado: https://fivemx.com/how-to-install-qbcore/ · https://fivemx.com/how-to-customize-qbcore-scripts/ · https://fivemx.com/qbcore-scripts/
Instalar y configurar: ox_inventory
Instalar
Agregue el recurso y asegúrese de que después biblioteca de buey.
-- recursos/[ox]/ox_inventory/fxmanifest.lua (fragmento) fx_version 'cerulean' juego 'gta5' lua54 'sí' scripts_compartidos { '@ox_lib/init.lua', 'config.lua' } scripts_del_cliente { 'cliente/*.lua' } scripts_del_servidor { '@oxmysql/lib/MySQL.lua', 'servidor/*.lua' }
servidor.cfg:
asegurar oxmysql asegurar ox_lib asegurar ox_inventory
Configuración del núcleo
Definir elementos (peso, pila, metadatos). Ruta típica: ox_inventory/datos/items.lua.
return { water = { label = 'Botella de agua', peso = 200, pila = verdadero, cierre = verdadero, descripción = 'Mantente hidratado.' }, sandwich = { label = 'Sándwich', peso = 300, pila = verdadero } }
Registrar una alijo y un tienda al iniciar el servidor:
-- server/stash_shop.lua CreateThread(function() exports.ox_inventory:RegisterStash('pd_evidence', 'Evidencia policial', 100, 100000, false, {police = 2}) exports.ox_inventory:RegisterShop('tienda_de_la_esquina', { nombre = 'Mercado 24/7', inventario = { { nombre = 'agua', precio = 8 }, { nombre = 'sándwich', precio = 12 } } }) fin)
Conceptos básicos de la interfaz de usuario
- Arrastrar y soltar, dividir, apilar; teclas de acceso rápido configurables.
- Usar metadatos Para seriales, calidades, caducidad.
Prueba rápida
Date un artículo y abre el inventario:
-- servidor/debug.lua RegisterCommand('dame', función(src) exportaciones.ox_inventory:AddItem(src, 'agua', 1) fin, verdadero)
Errores comunes
Advertencia: Hacer no Ejecute dos inventarios a la vez. Desactive completamente qb-inventory antes de activar ox_inventory.
Consejo: Elemento coincidente nombres exactamente en todos los trabajos/datos de elaboración e inventario.
Relacionado: https://fivemx.com/fivem-inventory-scripts/ · https://fivemx.com/qbcore-scripts/
Instalar y configurar: ox_lib
Lo esencial
Centro helpers you’ll use everywhere:
-- Comandos lib.addCommand('healme', { help = 'Cúrate a ti mismo (solo administrador).', restricto = 'group.admin' }, function(src) TriggerClientEvent('fivemx:heal', src) end) -- Menús contextuales lib.registerContext({ id = 'shop_menu', title = 'Mercado 24/7', options = { { title = 'Comprar agua ($8)', event = 'fivemx:buy', args = { item = 'water', price = 8 } }, { title = 'Comprar sándwich ($12)', event = 'fivemx:buy', args = { item = 'sandwich', price = 12 } } } }) -- más adelante lib.showContext('shop_menu')
Mini libro de cocina
- Diálogo de entrada & progreso con flujo esperable:
-- cliente entrada local = lib.inputDialog('Café artesanal', { { tipo = 'número', etiqueta = 'Granos (g)', predeterminado = 18, mínimo = 1, máximo = 60 } }) si entrada entonces local ok = lib.progressBar({ duración = 3500, etiqueta = 'Preparando…', useWhileDead = falso, canCancel = verdadero }) si ok entonces TriggerServerEvent('fivemx:craft:coffee', entrada[1]) fin fin
- Devoluciones de llamadas (el servidor valida, el cliente espera):
-- servidor lib.callback.register('fivemx:buyItem', function(src, item, price) -- validar trabajo/coords/etc. luego cobrar + otorgar -- devolver verdadero/falso y devolver mensaje exports.ox_inventory:AddItem(src, item, 1) fin) -- cliente local éxito = lib.callback.await('fivemx:buyItem', false, 'water', 8)
Relacionado: https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
Instalar y configurar: ox_target
Entidades y huesos
Adjuntar acciones a elementos específicos peatones/vehículos/objetos o sus huesos.
-- apuntar a una entidad por modelo exports.ox_target:addModel(`prop_vend_soda_02`, { { name = 'vending_buy', icon = 'fa-solid fa-bottle-water', label = 'Comprar una bebida', onSelect = function(data) TriggerEvent('fivemx:openVending') end } })
Zonas
Cree cajas/esferas/poligonos 3D con condiciones de trabajo.
-- Zona de caja delante de la caja registradora exports.ox_target:addBoxZone({ coords = vec3(25.7, -1347.3, 29.5), size = vec3(1.6, 1.2, 1.0), rotate = 0.0, debug = false, options = { { label = 'Abrir tienda', icon = 'fa-solid fa-store', groups = { police = 0, ambulance = 0 }, -- anyone; ejemplo de filtro de grupo onSelect = function() lib.showContext('shop_menu') end } } })
Ejemplos
- Objetivo del alijo para evidencia policial.
- Artesanía con restricciones de trabajo Dentro de un taller.
Relacionado: https://fivemx.com/qbcore-scripts/ · https://fivemx.com/fivem-inventory-scripts/
Instalar y configurar: oxmysql
¿Por qué oxmysql?
- Declaraciones preparadas, agrupamiento, API async/await.
- Mejor rendimiento y seguridad que string-concat SQL.
Hoja de referencia de la API
-- leer muchas filas locales = MySQL.query.await('SELECT id, name FROM players WHERE job = ?', { 'police' }) -- leer una sola fila local player = MySQL.single.await('SELECT * FROM players WHERE identifier = ?', { identifier }) -- valor escalar local count = MySQL.scalar.await('SELECT COUNT(*) FROM stash_items WHERE stash = ?', { 'pd_evidence' }) -- insertar id local = MySQL.insert.await('INSERT INTO logs (event, source) VALUES (?, ?)', { 'buy_water', src }) -- información local preparada y almacenada en caché = MySQL.prepare.await('SELECT label, weight FROM items WHERE name = ?', { 'water' }) -- transacción MySQL.transaction.await(function() MySQL.query.await('UPDATE accounts SET dinero = dinero - ? WHERE identificador = ?', { 12, identificador }) MySQL.query.await('INSERT INTO compras (identificador, artículo) VALORES (?, ?)', { identificador, 'sándwich' }) fin)
Higiene de índices y esquemas
ALTER TABLE jugadores AÑADIR ÍNDICE idx_players_identifier (identificador); ALTER TABLE compras AÑADIR ÍNDICE idx_purchases_identifier_created (identificador, creado_en);
Manejo de errores
Consejo: Habilite las advertencias de consultas lentas en el entorno de pruebas y agregue índices adecuados antes del lanzamiento.
Relacionado: https://fivemx.com/mysql-async-to-oxmysql/ · https://fivemx.com/sql-identifiers-migration/ · https://fivemx.com/converting-fivem-scripts/
Manuales de migración (listos para copiar y pegar)
inventario qb → inventario_ox
Mapeo de conceptos
| Concepto | inventario qb | inventario_de_bueyes |
|---|---|---|
| Elementos | qb-core/shared/items.lua | ox_inventory/datos/items.lua |
| Escondites | Lógica de almacenamiento de trabajos y jugadores en scripts | RegisterStash(id, etiqueta, ranuras, peso, propietario, grupos, coordenadas) |
| Tiendas | qb-tiendas o personalizadas | RegistrarTienda(id, { inventario = {..} }) |
Pasos
- Deshabilite qb-inventory y cualquier IU dependiente del inventario.
- Instalar biblioteca de buey, inventario_de_bueyes, oxmysql En ese orden.
- Elementos del puerto →
datos/elementos.lua(preservar nombres/pesos/metadatos). - Reemplazar las llamadas de agregar o quitar elementos con
exportaciones.ox_inventory:Agregar artículo/Eliminar artículo. - Registrar escondites/tiendas en el servidor; migrar los datos guardados de los escondites si corresponde.
- Prueba en puesta en escena; verificar arrastre/apilamiento/división y almacenamiento de trabajos.
Lista de verificación (antes/después)
| Área | Antes | Después | Riesgo |
|---|---|---|---|
| Recursos | qb-inventory habilitado | qb-inventory eliminado, ox_inventory asegurado | Bajo |
| Elementos | elementos en qb compartidos | artículos en datos/elementos.lua | Medio (nombramiento) |
| Escondites | implícito | explícito RegistrarseStash | Bajo |
| Tiendas | tiendas qb | RegistrarseTienda | Bajo |
Ejemplo: agregar/eliminar reemplazar
-- antes (pseudocódigo qb-inventory) -- QBCore.Functions.AddItem(src, 'agua', 1) -- después (ox_inventory) exportaciones.ox_inventory:AddItem(src, 'agua', 1) exportaciones.ox_inventory:RemoveItem(src, 'sándwich', 1)
Relacionado: https://fivemx.com/fivem-inventory-scripts/
mysql-async → oxmysql
Patrones de búsqueda y reemplazo
| llamada mysql-async | equivalente de oxmysql |
|---|---|
MySQL.Async.fetchAll(sql, parámetros, cb) | MySQL.query(sql, parámetros) / .esperar |
MySQL.Async.fetchScalar(sql, parámetros, cb) | MySQL.scalar(sql, parámetros) / .esperar |
MySQL.Async.execute(sql, parámetros, cb) | MySQL.query(sql, parámetros) o MySQL.update/insert / .esperar |
concatenación de cadenas "..var.." | ? marcadores de posición con matriz de parámetros |
| manual COMIENZO/CONFIRMACIÓN | MySQL.transaction.await(función() ... fin) |
Ejemplo de refactorización
-- antes de MySQL.Async.fetchAll('SELECT * FROM users WHERE identifier = @id', { ['@id'] = identifier }, function(rows) -- usar filas fin) -- después de filas locales = MySQL.query.await('SELECT * FROM users WHERE identifier = ?', { identifier })
Declaraciones preparadas
usuario local = MySQL.prepare.await('SELECT id, job FROM users WHERE identificador = ?', { identificador })
Advertencia: Nunca confíes en la información del cliente. Valida siempre en el servidor y utilizar marcadores de posición.
Relacionado: https://fivemx.com/mysql-async-to-oxmysql/ · https://fivemx.com/sql-identifiers-migration/ · https://fivemx.com/converting-fivem-scripts/
Patrones que venden: creación de trabajos e interfaz de usuario con la pila Ox
Un trabajo de entrega mínimo que vincula objetivo_buey (interactuar), biblioteca de buey (IU), inventario_de_bueyes (recompensas), y oxmysql (auditoría).
-- cliente/jobs_delivery.lua local drop = vec3(120.4, -1039.2, 29.2) exportaciones.ox_target:addBoxZone({ coordenadas = drop, tamaño = vec3(1.4, 1.0, 1.0), rotación = 340.0, opciones = { { nombre = 'entregar_caja', etiqueta = 'Entregar caja', icono = 'fa-solid fa-box', onSelect = función() local ok = lib.progressBar({ duración = 4000, etiqueta = 'Entregando…' }) si está bien entonces TriggerServerEvent('fivemx:job:deliverCrate') fin fin } } })
-- server/jobs_delivery.lua RegisterNetEvent('fivemx:job:deliverCrate', function() local src = source -- límite de velocidad por minuto (muy simple) local ok = exports.ox_inventory:AddItem(src, 'water', 1) si es ok entonces MySQL.insert.await('INSERT INTO job_logs (identifier, event) VALUES (?, ?)', { GetPlayerIdentifier(src, 0), 'deliver_crate' }) TriggerClientEvent('ox_lib:notify', src, { title = 'Entrega', description = 'Recibió agua x1', type = 'success' }) end end)
Relacionado: https://fivemx.com/qbcore-scripts/ · https://fivemx.com/fivem-inventory-scripts/
Rendimiento y seguridad
- Eliminar el rebote de las interacciones de los objetivos y evitar zonas superpuestas.
- Almacenar en caché lecturas frecuentes; índice columnas utilizadas en WHERE/JOIN.
- Mantenga bajos los ticks del servidor y mueva los bucles pesados fuera del hilo principal.
- Seguridad: validar el lado del servidor, limitar la velocidad de las acciones económicas y registrar eventos sensibles.
Consejo: Activar advertencias de consultas lentas en el entorno de pruebas; enviar índices con migraciones.
Relacionado: https://fivemx.com/converting-fivem-scripts/ · https://fivemx.com/sql-identifiers-migration/
Depuración y arnés de prueba
- Agregar depuración comandos custodiado por permisos.
- Registra fallos de la base de datos y cortocircuitos en caso de errores.
- Pruebe la recarga en caliente reiniciando recursos individuales (no toda la pila).
lib.addCommand('oxping', { help = 'Control de estado', restricto = 'group.admin' }, function(src) local ok = MySQL.scalar.await('SELECT 1') == 1 TriggerClientEvent('ox_lib:notify', src, { title = 'Ox Health', description = ok y 'DB OK' o 'DB FAIL', type = ok y 'success' o 'error' }) end)
Relacionado: https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
Recursos internos y próximos pasos
- Marcos: https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
- QBCore: https://fivemx.com/how-to-install-qbcore/ · https://fivemx.com/how-to-customize-qbcore-scripts/ · https://fivemx.com/qbcore-scripts/
- Migraciones: https://fivemx.com/mysql-async-to-oxmysql/ · https://fivemx.com/sql-identifiers-migration/ · https://fivemx.com/converting-fivem-scripts/
- Centro de inventario: https://fivemx.com/fivem-inventory-scripts/
Explorar la tienda para scripts probados que siguen estos patrones.
Preguntas frecuentes
¿Es ox_inventory más rápido que qb-inventory?
Generalmente sí. Se centra en una interfaz de usuario eficiente y operaciones del lado del servidor con valores predeterminados sensatos para pilas, pesos y metadatos.
¿Puedo mezclar qb-inventory y ox_inventory?
No recomendado. Detenga qb-inventory por completo antes de habilitar ox_inventory para evitar controladores duplicados y la desincronización de elementos.
¿Necesito reescribir SQL para oxmysql?
Principalmente búsqueda y reemplazo. Reemplazar la cadena concat con marcadores de posición, adoptar *.esperar API y agregue índices faltantes.
¿Cómo puedo proteger las interacciones de ox_target?
Usar grupos/job verifica el lado del cliente pero siempre vuelve a validar en el servidor (distancia, trabajo, propiedad del artículo) antes de las recompensas.
¿Qué pasa con la compatibilidad con ESX?
La pila Ox es independiente del framework. Asigne eventos de ESX a los controladores del servidor y mantenga la coherencia en los nombres de inventario.
¿Cómo puedo comparar las llamadas a bases de datos?
Utilice EXPLAIN, habilite las advertencias de consultas lentas y compare los tiempos antes y después de agregar índices.
¿Dónde defino artículos para ox_inventory?
En ox_inventory/datos/items.luaMantenga las etiquetas breves y los pesos realistas.
¿Puedo conservar qtarget mientras migro a ox_target?
Temporalmente, pero evitando la superposición de zonas. Migrar característica por característica y eliminar qtarget cuando se alcance la paridad.
¿Cómo migro datos almacenados?
Crear equivalente RegistrarseStash Entradas y ejecutar SQL para renombrar los antiguos ID de almacenamiento temporal con las nuevas claves, si es necesario. Prueba en el entorno de pruebas.
¿Cómo establezco pesos y límites?
Los pesos viven en items.luaLas capacidades de almacenamiento/tienda son parte de RegistrarseStash/RegistrarseTienda argumentos.
¿Cómo puedo limitar la frecuencia de compras o trabajos?
Usar lib.addCommand/devoluciones de llamadas con tiempos de recuperación en memoria simples y validación del lado del servidor.
¿Oxmysql admite transacciones?
Sí, envuelva las secuencias atómicas en MySQL.transaction.await(función() ... fin).
¿Cómo manejo NUI con Ox?
Ox funciona bien con cualquier NUI; solo mantenga la lógica de UI pesada en el lado del cliente y las validaciones en el lado del servidor.
¿Cuál es el orden de migración más seguro?
oxmysql → ox_lib → ox_inventory → ox_target. Validar después de cada paso.
Registro de cambios y créditos
| Versión | Fecha | Notas |
|---|---|---|
| versión 1.0 | 2025-09-05 | Publicación inicial con manuales de instalación, configuración y migración. |
Última actualización: 2025-09-05
Créditos y fuentes: Documentación extensa (ox_inventory, ox_lib, ox_target), referencia de oxmysql, documentación de Cfx.re y mejores prácticas de la comunidad.
Conclusión y próximos pasos
Ambos marcos pueden gestionar una ciudad de primer nivel. La diferencia radica en el legado que se desea transmitir y en el nivel de estandarización que se desea para el futuro.
Próximos pasos:
- Explorar Scripts de QBOX → https://fivemx.com/qbox-scripts/
- Explorar Scripts de QBCore → https://fivemx.com/qbcore-scripts/
- Leer más en Conversión del marco → https://fivemx.com/framework-conversion
Referencias externas (más información)
- QBOX GitHub (núcleo qbx) → https://github.com/Qbox-project/qbx_core
- QBCore GitHub (núcleo qb) → https://github.com/qbcore-framework/qb-core
- Documentación de FiveM: Manifiesto de recursos (fxmanifest.lua) → https://docs.fivem.net/docs/scripting-reference/resource-manifest/resource-manifest/
Migration checks
- List every resource that calls QBCore exports or events.
- Check inventory compatibility before changing item definitions.
- Test shops, jobs, player loading, money, vehicles, and housing on staging.
- Review ox_lib callbacks and notifications where scripts already depend on them.
- Keep a database rollback before changing live framework tables.
Related framework guides
