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

198 instalações no skills.sh

Atualizado em

Baixar SKILL.mdComunidade

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

O QBCore é um framework de roleplay do FiveM construído em torno do objeto Player, empregos, gangues, inventário e callbacks. Este guia cobre a API principal, os erros que quebram scripts QBCore e a skill de IA que escreve código contra a API real.

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 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

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