QBCore para FiveM: qué es, errores comunes y la skill de IA

198 instalaciones en skills.sh

Actualizado

Descargar SKILL.mdComunidad

¿No quieres gestionar las skills tú mismo? Consigue la app completa.

QBCore es un framework de rol de FiveM construido alrededor del objeto Player, trabajos, bandas, inventario y callbacks. Esta guía cubre su API principal, los errores que rompen scripts QBCore y la skill de IA que escribe código contra la API real.

QBCore es un framework de roleplay para FiveM que gestiona jugadores, trabajos, bandas, dinero e inventario a través del recurso qb-core y un conjunto de módulos qb-. Si programas para un servidor QBCore, trabajas con el objeto QBCore, el objeto Player en el servidor y PlayerData en el cliente. Esta página explica qué documenta la skill de QBCore de FiveAI, los errores que más rompen scripts QBCore y cómo instalar la skill en tu asistente de IA.

Qué te da la skill de QBCore

La skill es un archivo SKILL.md con un archivo de reglas por cada área del framework:

  • core-concepts: cómo se inicializa qb-core, la forma de PlayerData y qué contiene el objeto Player en el servidor.
  • client-functions y server-functions: notificaciones y estado del jugador en el cliente, QBCore.Functions.GetPlayer(source) en el servidor, callbacks e items usables.
  • player-methods: los métodos de Player.Functions para dinero, items, trabajos, bandas, metadata y cuentas.
  • jobs-gangs: los sistemas de trabajos y bandas, pagos y estado de servicio (duty).
  • inventory-items: manejo de items y el flujo de items usables.
  • events-callbacks: eventos de QBCore, callbacks de servidor, callbacks de cliente y manejo de eventos.
  • best-practices: comprobaciones de nil, objetos de jugador cacheados, tiempos de Wait dinámicos, camelCase, locales antes que globales y ox_lib para menús, diálogos, notificaciones y barras de progreso.

Recurre a ella cuando crees un recurso QBCore, añadas un trabajo o una banda, toques dinero o items, o leas datos del jugador en cualquier sitio.

Errores comunes con QBCore

  • Usar Player sin comprobar nil. Síntoma: "attempt to index a nil value" en la consola del servidor cuando el source ya se fue o no es válido. Solución: local Player = QBCore.Functions.GetPlayer(source) seguido de if not Player then return end.
  • Mezclar xPlayer (ESX) y Player (QBCore). Síntoma: una llamada a xPlayer.addMoney en un recurso QBCore y un error de nil en ejecución. El script se adaptó de un ejemplo de ESX. Solución: usa QBCore.Functions.GetPlayer y solo los métodos de Player.Functions.
  • Leer PlayerData en el cliente antes de que el jugador cargue. Síntoma: trabajo o citizen id vacíos justo después del spawn. Solución: espera al estado de jugador cargado antes de tocar PlayerData, como describe la regla de funciones de cliente.
  • Confiar en las cantidades que envía el cliente. Síntoma: un cliente modificado dispara tu evento de servidor con un precio inventado y el servidor lo acepta. Solución: calcula precios y recompensas en el servidor, valida el source y asegura tus eventos.
  • Bucles Wait(0) que nunca duermen. Síntoma: un hilo de cliente que corre cada frame aunque el jugador esté lejos de la zona que vigila, y un recurso con tiempo alto en resmon. Solución: usa tiempos de Wait dinámicos, cortos cerca del punto de interés y largos en el resto.

Por qué los asistentes de IA se equivocan con QBCore

Un asistente genérico mezcla versiones de QBCore y frameworks. A menudo obtiene el objeto core con el patrón antiguo basado en el evento QBCore:GetObject en vez del export exports['qb-core']:GetCoreObject(), inventa métodos de Player.Functions que no existen o escribe lógica de bandas con funciones de trabajos porque se parecen. También coloca llamadas exclusivas de servidor como GetPlayer en un archivo de cliente, y eso falla en ejecución.

La skill le da al asistente una referencia compacta y actual. Los archivos core-concepts y player-methods listan la forma real del objeto y sus métodos, jobs-gangs separa los dos sistemas, y los principios (comprobar nil, esperar la carga del jugador, no confiar en el cliente, cachear objetos de jugador, Wait dinámico, ox_lib para la UI) se cargan cada vez que pides código QBCore. El resultado es un script que usa la API que corre tu servidor, no una mezcla de tres tutoriales.

Instala la skill de QBCore en 30 segundos

  1. Haz clic en "Download SKILL.md" en la parte superior de esta página.
  2. Descomprímelo en la carpeta de skills o reglas de tu herramienta de IA. La sección de instalación de abajo muestra la ruta exacta para Claude Code, Cursor y VS Code.
  3. Pide al asistente algo concreto, como un item usable que compruebe el trabajo del jugador antes de pagar, y confirma que usa QBCore.Functions.GetPlayer con comprobación de nil.

Cómo instalar esta skill

Descarga el zip, descomprímelo y coloca la carpeta donde tu herramienta carga skills o reglas. La ruta exacta depende de la herramienta:

Claude Code

Descomprime en .claude/skills/qbcore-framework/ dentro del proyecto (la carpeta debe contener SKILL.md). Para todos los proyectos, usa ~/.claude/skills/qbcore-framework/.

Documentación de skills de Claude Code

Cursor

Cursor carga las reglas del proyecto desde .cursor/rules/. Añade ahí un archivo de regla que apunte a la skill descomprimida, o pega el contenido de SKILL.md y los archivos de reglas en una regla. El formato es .mdc con frontmatter y cambia entre versiones, así que revisa la documentación de tu versión.

Documentación de reglas de Cursor

VS Code / Copilot

Copilot lee archivos de instrucciones desde .github/instructions/*.instructions.md. Copia SKILL.md ahí con un glob applyTo para tus archivos Lua y deja los archivos de reglas al lado.

Documentación de instrucciones de VS Code

El archivo SKILL.md

Este es el archivo que lee tu asistente de IA. Enlaza a los archivos de reglas incluidos en la descarga.

Contenido de la skill (incluye SKILL.md y cualquier otro archivo)

El contenido de la skill está en inglés: es documentación técnica pensada para agentes de IA.

QBCore Framework Development

Complete guide for developing with QBCore Framework — a comprehensive FiveM roleplay framework providing core functionalities and modules.

When to use

  • Creating or editing QBCore resources/scripts
  • Working with player data (Player object, PlayerData)
  • Implementing jobs, gangs, economy, or inventory systems
  • Using QBCore client/server functions, callbacks, or events
  • Questions about QBCore best practices and optimization

How to use

Read individual rule files for detailed explanations and examples:

  • rules/core-concepts.md — QBCore architecture, PlayerData structure, Player object, framework initialization
  • rules/client-functions.md — Client-side QBCore functions, notifications, player state management
  • rules/server-functions.md — Server-side functions, player retrieval, callbacks, usable items
  • rules/player-methods.md — Player object methods: money, items, jobs, gangs, metadata, accounts
  • rules/jobs-gangs.md — Job system, gang system, payments, duty status
  • rules/inventory-items.md — Inventory management, item handling, usable items
  • rules/events-callbacks.md — QBCore events, server callbacks, client callbacks, event handling
  • rules/best-practices.md — QBCore coding standards, optimization, security, naming conventions
  • rules/reference-links.md — Official QBCore documentation links

Key principles

  1. Always check for nil — if Player then ... end before using Player object
  2. Use QBCore.Functions.GetPlayer — Standard player retrieval: local Player = QBCore.Functions.GetPlayer(source)
  3. Wait for player load — Check player loaded state on client before accessing PlayerData
  4. Never trust client — Validate all data server-side, secure your events
  5. Follow QBCore patterns — Use QBCore functions instead of reinventing (callbacks, notifications, etc.)
  6. Optimize loops — Cache player objects, use dynamic Wait times, avoid unnecessary calls
  7. Use camelCase — Follow Lua naming: myVariable, local over global
  8. Minimal globals — Keep variables local unless they need global scope
  9. Use ox_lib for UI — Prefer ox_lib for menus, dialogs, notifications, progress bars

Preguntas frecuentes

¿Qbox es lo mismo que QBCore?
No. Qbox es un fork de QBCore con sus propios cambios. Esta skill apunta a QBCore. Buena parte del objeto Player y la lógica de trabajos coincide, pero revisa los exports y los nombres de funciones antes de correr código QBCore en un servidor Qbox.
¿La skill cubre qb-inventory u ox_inventory?
Cubre las funciones de items e inventario del objeto Player de QBCore y el flujo de items usables. Los recursos de inventario como qb-inventory y ox_inventory tienen sus propios exports; para esos consulta su documentación.
¿Puedo usar esta skill con ChatGPT?
Sí. SKILL.md es markdown plano. Pégalo en una instrucción personalizada o adjúntalo a un proyecto de ChatGPT. Claude Code, Cursor y VS Code lo leen desde su carpeta de skills o reglas.

Guías relacionadas

Lecturas más largas del blog de FiveAI sobre el mismo tema.

Más skills