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

198 instalaciones en skills.sh

Descargar SKILL.md Comunidad

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

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

Server/client API for qb-core: Player object, PlayerData, callbacks, jobs, gangs, money and metadata.

Activation Contract

Load this skill when the user creates or edits a qb-core resource, touches Player / QBCore.PlayerData, needs jobs, gangs, money, items or metadata through QBCore, or asks about QBCore callbacks, events or best practices.

This skill targets qb-core (qbcore-framework). If the user is on Qbox (qbx_core, exports.qbx_core), the APIs diverge: state it and do not apply this skill blindly.

Hard Rules

  • Acquire the core once with local QBCore = exports['qb-core']:GetCoreObject(); never call it inside every function.
  • Player exists on the SERVER only (QBCore.Functions.GetPlayer(source)). QBCore.PlayerData exists on the CLIENT only, populated after QBCore:Client:OnPlayerLoaded.
  • Always nil-check: if not Player then return end before calling any method.
  • Money, jobs, gangs, items and metadata are mutated on the server through Player.Functions.*, never from the client.
  • Pass a reason to AddMoney, RemoveMoney, SetMoney.
  • Use state bags OR events for a given piece of state, never both.
  • Validate every client-supplied argument on the server; never trust amounts, prices or item names sent by the client.
  • Prefer ox_lib for notifications, menus, dialogs and progress bars.
  • Use dynamic Wait() values in loops; avoid Wait(0) unless per-frame work is required.

Decision Gates

Need Use
Client asks server for data QBCore.Functions.CreateCallback + QBCore.Functions.TriggerCallback
Money Player.Functions.AddMoney/RemoveMoney/SetMoney/GetMoney(moneyType, ...)
Job / duty / gang Player.Functions.SetJob, SetJobDuty, SetGang
Persistent per-player flags Player.Functions.SetMetaData / GetMetaData
Items (qb-inventory) Player.Functions.AddItem/RemoveItem/GetItemByName/GetItemBySlot
Shared runtime state state bags (see rules/core-concepts.md)

Execution Steps

  1. Confirm qb-core starts before the resource; cache QBCore per side.
  2. Decide the side: mutation and validation on server, display on client.
  3. Fetch Player, nil-check, then validate every client-supplied argument.
  4. Pick the call from Decision Gates; read the matching rules file for signatures.
  5. Return data via callbacks, not paired events.

Output Contract

Return runnable Lua with the client/server split explicit, Player nil-checked, and reasons on money operations. Use ox_lib for UI unless the user asks otherwise.

References

  • rules/core-concepts.md — architecture, PlayerData, Player object, events, state bags.
  • rules/player-methods.md — Player.Functions money, job, gang, metadata, items.
  • rules/best-practices.md — naming, caching, waits, state management, security.
  • rules/reference-links.md — official QBCore documentation links.

Upstream docs: https://docs.qbcore.org

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