Manual do qbx_core

O framework principal para Qbox — base para servidores FiveM com suporte a multicharacter, múltiplos trabalhos/gangues, veículos persistentes e sistema de hooks.

Funcionalidades Principais

Sistema de Jogador

• Multicharacter: Criação e gerenciamento de múltiplos personagens por jogador
• Multi-Trabalho/Gangue: Suporte a múltiplos trabalhos e gangues simultâneos por jogador
• Metadata: Sistema completo de metadados (fome, sede, estresse, vida, colete, etc.)
• Persistência: Dados salvos automaticamente no banco de dados

Sistema de Grupos

• Trabalhos: Definição de trabalhos com graus, salários e permissões
• Gangues: Sistema completo de gangues com hierarquia
• Gerenciamento: Adicionar/remover jogadores, alterar graus, definir grupo principal

Veículos Persistentes

• Salva estado, propriedades, garagem e danos dos veículos
• Transferência de propriedade entre jogadores
• Rastreamento de estado (OUT, GARAGED, IMPOUNDED)

Sistema de Hooks

• Hooks estilo Ox para estender funcionalidades
• Eventos disparados em ações importantes do core

Anti-Cheat e Segurança

• Detecção de exploits integrada
• Desconexão automática de jogadores suspeitos

Sistema de Fila

• Fila integrada para servidores cheios
• Whitelist configurável (servidor aberto/fechado)

Configuração

config/shared.lua

Config = {
    Spawn = vector4(-1037.37, -2737.66, 13.76, 206.12), -- Spawn padrão
    Player = {
        DefaultHealth = 200,
        DefaultArmor = 0,
        DefaultHunger = 100,
        DefaultThirst = 100,
    },
    Money = {
        types = {'cash', 'bank', 'crypto'}
    }
}

config/server.lua

Config = {
    Logging = {
        webhook = '', -- URL do webhook Discord
        types = {'join', 'leave', 'death', 'commands'}
    },
    PvP = true, -- Ativar/desativar PvP global
    ClosedServer = false, -- Servidor fechado (whitelist)
}

config/client.lua

Config = {
    MapText = 'Qbox Framework', -- Texto na tela de pause
    EnableDebug = false,
}

Metadata do Jogador

Comandos

Administradores

Jogadores

Exports (API)

Server Exports

Client Exports

Eventos

Server Events

Client Events

Estrutura de Arquivos

qbx_core/
├── client/
│   ├── main.lua           # Inicialização, dados de veículos, exports
│   ├── groups.lua          # Gerenciamento de grupos
│   ├── functions.lua       # Funções utilitárias
│   ├── loops.lua           # Loops do client
│   ├── events.lua          # Handlers de eventos
│   ├── character.lua       # Gerenciamento de personagem
│   ├── discord.lua         # Discord rich presence
│   └── bridge/qb/         # Ponte de compatibilidade QB
├── server/
│   ├── main.lua           # Inicialização, exports, jogadores
│   ├── player.lua         # Dados do jogador, trabalhos, gangues
│   ├── groups.lua          # Gerenciamento de grupos
│   ├── commands.lua        # Comandos admin/jogador
│   ├── character.lua       # Criação de personagem
│   └── storage.lua         # Banco de dados
├── shared/
│   ├── jobs.lua           # Definições de trabalhos
│   ├── gangs.lua          # Definições de gangues
│   ├── items.lua           # Definições de itens
│   ├── vehicles.lua       # Dados de veículos
│   └── weapons.lua        # Dados de armas
├── modules/
│   ├── lib.lua            # Funções da biblioteca
│   ├── logger.lua         # Módulo de logging
│   ├── hooks.lua          # Sistema de hooks
│   └── playerdata.lua     # Dados do jogador
└── config/                # Arquivos de configuração

Dependências

Solução de Problemas

Jogador não consegue fazer login

• Verifique se o banco de dados está rodando
• Confirme se o oxmysql está iniciado antes do qbx_core
• Verifique os logs do servidor para erros de banco de dados

Trabalho/gangue não atualiza

• Verifique se o evento OnJobUpdate/OnGangUpdate está sendo disparado
• Confirme se o jogador está online ao usar exports de servidor

Metadados não salvam

• Verifique se o campo existe na tabela players
• Confirme se o tipo de dado é compatível
• Use SetMetadata ao invés de alterar diretamente

Erro de compatibilidade QB

• O qbx_core usa ponte QB em client/bridge/qb/ e server/bridge/qb/
• Verifique se os eventos QBCore estão sendo disparados corretamente