QBCore para FiveM: o que é, erros comuns e a skill de IA

198 instalações no skills.sh

Baixar SKILL.md Comunidade

Não quer gerenciar as skills por conta própria? Obtenha o app completo.

O QBCore é um framework de roleplay para FiveM que gerencia jogadores, empregos, gangues, dinheiro e inventário através do recurso qb-core e de um conjunto de módulos qb-. Se você programa para um servidor QBCore, trabalha com o objeto QBCore, o objeto Player no servidor e o PlayerData no cliente. Esta página explica o que a skill de QBCore da FiveAI documenta, os erros que mais quebram scripts QBCore e como instalar a skill no seu assistente de IA.

O que a skill de QBCore te dá

A skill é um arquivo SKILL.md com um arquivo de regras para cada área do framework:

  • core-concepts: como o qb-core inicializa, a estrutura do PlayerData e o que o objeto Player guarda no servidor.
  • client-functions e server-functions: notificações e estado do jogador no cliente, QBCore.Functions.GetPlayer(source) no servidor, callbacks e itens usáveis.
  • player-methods: os métodos de Player.Functions para dinheiro, itens, empregos, gangues, metadata e contas.
  • jobs-gangs: os sistemas de empregos e gangues, pagamentos e status de serviço (duty).
  • inventory-items: manipulação de itens e o fluxo de itens usáveis.
  • events-callbacks: eventos do QBCore, callbacks de servidor, callbacks de cliente e tratamento de eventos.
  • best-practices: checagem de nil, objetos de jogador em cache, tempos de Wait dinâmicos, camelCase, locais em vez de globais e ox_lib para menus, diálogos, notificações e barras de progresso.

Recorra a ela quando criar um recurso QBCore, adicionar um emprego ou uma gangue, mexer em dinheiro ou itens, ou ler dados do jogador em qualquer lugar.

Erros comuns com QBCore

  • Usar Player sem checar nil. Sintoma: “attempt to index a nil value” no console do servidor quando o source já saiu ou é inválido. Correção: local Player = QBCore.Functions.GetPlayer(source) seguido de if not Player then return end.
  • Misturar xPlayer (ESX) e Player (QBCore). Sintoma: uma chamada a xPlayer.addMoney em um recurso QBCore e um erro de nil em execução. O script foi adaptado de um exemplo de ESX. Correção: use QBCore.Functions.GetPlayer e apenas os métodos de Player.Functions.
  • Ler PlayerData no cliente antes de o jogador carregar. Sintoma: emprego ou citizen id vazios logo depois do spawn. Correção: espere o estado de jogador carregado antes de tocar no PlayerData, como descreve a regra de funções de cliente.
  • Confiar nos valores enviados pelo cliente. Sintoma: um cliente modificado dispara seu evento de servidor com um preço inventado e o servidor aceita. Correção: calcule preços e recompensas no servidor, valide o source e proteja seus eventos.
  • Loops Wait(0) que nunca dormem. Sintoma: uma thread de cliente que roda a cada frame mesmo com o jogador longe da zona que ela vigia, e um recurso com tempo alto no resmon. Correção: use tempos de Wait dinâmicos, curtos perto do ponto de interesse e longos no resto.

Por que os assistentes de IA erram com QBCore

Um assistente genérico mistura versões do QBCore e frameworks. Ele costuma obter o objeto core com o padrão antigo baseado no evento QBCore:GetObject em vez do export exports['qb-core']:GetCoreObject(), inventa métodos de Player.Functions que não existem ou escreve lógica de gangues com funções de empregos porque as duas se parecem. Também coloca chamadas exclusivas de servidor como GetPlayer em um arquivo de cliente, e isso falha em execução.

A skill dá ao assistente uma referência compacta e atual. Os arquivos core-concepts e player-methods listam a estrutura real do objeto e seus métodos, jobs-gangs separa os dois sistemas, e os princípios (checar nil, esperar o jogador carregar, nunca confiar no cliente, cachear objetos de jogador, Wait dinâmico, ox_lib para UI) são carregados toda vez que você pede código QBCore. O resultado é um script que usa a API que roda no seu servidor, e não uma mistura de três tutoriais.

Instale a skill de QBCore em 30 segundos

  1. Clique em “Download SKILL.md” no topo desta página.
  2. Descompacte na pasta de skills ou regras da sua ferramenta de IA. A seção de instalação abaixo mostra o caminho exato para Claude Code, Cursor e VS Code.
  3. Peça ao assistente algo concreto, como um item usável que confira o emprego do jogador antes de pagar, e verifique se ele usa QBCore.Functions.GetPlayer com checagem de nil.

Como instalar esta skill

Baixe o zip, descompacte e coloque a pasta onde a sua ferramenta carrega skills ou regras. O caminho exato depende da ferramenta:

Claude Code

Descompacte em .claude/skills/qbcore-framework/ dentro do projeto (a pasta precisa conter SKILL.md). Para todos os projetos, use ~/.claude/skills/qbcore-framework/.

Documentação de skills do Claude Code

Cursor

O Cursor carrega as regras do projeto de .cursor/rules/. Adicione ali um arquivo de regra apontando para a skill descompactada, ou cole o conteúdo do SKILL.md e dos arquivos de regras em uma regra. O formato é .mdc com frontmatter e muda entre versões, então confira a documentação da sua versão.

Documentação de regras do Cursor

VS Code / Copilot

O Copilot lê arquivos de instruções em .github/instructions/*.instructions.md. Copie o SKILL.md para lá com um glob applyTo para os seus arquivos Lua e mantenha os arquivos de regras ao lado.

Documentação de instruções do VS Code

O arquivo SKILL.md

Este é o arquivo que o seu assistente de IA lê. Ele aponta para os arquivos de regras incluídos no download.

Conteúdo da skill (inclui SKILL.md e quaisquer outros arquivos)

O conteúdo da skill está em inglês: é documentação técnica feita 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

Perguntas frequentes

Qbox é a mesma coisa que QBCore?
Não. O Qbox é um fork do QBCore com mudanças próprias. Esta skill mira o QBCore. Boa parte do objeto Player e da lógica de empregos coincide, mas confira os exports e os nomes de funções antes de rodar código QBCore em um servidor Qbox.
A skill cobre qb-inventory ou ox_inventory?
Ela cobre as funções de itens e inventário do objeto Player do QBCore e o fluxo de itens usáveis. Recursos de inventário como qb-inventory e ox_inventory têm seus próprios exports; para esses, leia a documentação deles.
Posso usar esta skill com o ChatGPT?
Sim. O SKILL.md é markdown puro. Cole em uma instrução personalizada ou anexe a um projeto do ChatGPT. Claude Code, Cursor e VS Code leem o arquivo da pasta de skills ou regras.

Guias relacionados

Leituras mais longas do blog da FiveAI sobre o mesmo tema.

Mais skills