mri_Qstarterpack — Manual

Kit inicial entregue uma única vez por jogador: itens, dinheiro e veículo, retirados com um NPC no mundo (ou por comando), com regras/quiz/captcha opcionais e registro em banco.

Sumário

1. Dependências
2. Instalação
3. Permissões (ACE)
4. Configuração
5. Locais de retirada (Config.Locations)
6. Diálogo de entrada (regras, quiz, captcha)
7. Comandos
8. Banco de dados
9. Log no Discord
10. Integrações
11. Limitações conhecidas
12. Entrypoints para outros recursos
13. Localização
14. Estrutura de arquivos

Dependências

O shared/core.lua valida na inicialização que os recursos apontados por Config.TargetResource, Config.InventoryResource e Config.SQLResource estão realmente iniciados, e derruba o recurso com erro se algum não estiver (o target é ignorado quando Config.UseTarget = false).

Instalação

1. Copie a pasta mri_Qstarterpack para resources/.
2. Importe o SQL:

   tcd_starterpack.sql
   Com Config.DBChecking = true (padrão), o recurso cria a tabela e as colunas faltantes sozinho na inicialização — a importação manual é o caminho garantido.
3. Adicione ao server.cfg:

   ensure mri_Qstarterpack
4. Ajuste shared/config.lua: os recursos de target/inventário, os itens de Config.StarterPackItems e as coordenadas de Config.Locations (o local que vem no config é o porto sul de Los Santos).
5. Se quiser log no Discord, preencha o webhook em server/functions/discordlog.lua.

Não há conflito conhecido com outros recursos. Os eventos e callbacks mantêm o prefixo upstream cfx-tcd-starterpack:.

Permissões (ACE)

Apenas o comando de auditoria é restrito, via lib.addCommand com restricted = 'group.admin':

add_principal identifier.license:<licenca_do_admin> group.admin

O ox_lib cria a ACE command.checkpacks automaticamente para o grupo. O nome acompanha Config.CheckPacksCommand — se você renomear o comando, o nome da ACE muda junto.

O comando de resgate (Config.CommandConfig.command) não é restrito: qualquer jogador pode usá-lo, e o controle é feito pelo registro de “já recebeu” no banco.

Configuração

Arquivo: shared/config.lua.

Opções globais

Funções de integração

Três funções do config podem ser reescritas para adaptar o recurso ao seu servidor:

Comando de resgate (Config.CommandConfig)

O comando também exige que o jogador esteja dentro do receiving_radius de algum local de Config.Locations — ele não funciona de qualquer lugar do mapa.

Locais de retirada (Config.Locations)

Cada entrada de Config.Locations spawna um NPC e define o que ele entrega. A chave é livre (["1"], ["porto"], …).

Os NPCs de todos os locais são criados na inicialização do client e removidos no onResourceStop. Peds do jogo que estejam a menos de 1 metro do ponto são apagados antes do spawn, para não empilhar modelos.

Diálogo de entrada (regras, quiz, captcha)

Config.DialogInfo adiciona uma etapa antes da entrega. Só um tipo fica ativo por vez.

Comandos

Banco de dados

Tabela tcd_starterpack (arquivo tcd_starterpack.sql):

CREATE TABLE `tcd_starterpack` (
  `id` int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY,
  `name` varchar(50) NOT NULL,
  `identifier` varchar(50) NOT NULL,
  `received` tinyint(1) NOT NULL,
  `date_received` datetime DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

Uma linha é criada com received = 0 na primeira vez que o jogador é verificado, e atualizada para 1 na entrega. /checkpacks é o caminho para reverter (reset) ou apagar um registro.

Log no Discord

Configurado em server/functions/discordlog.lua:

O embed enviado a cada entrega contém nome do personagem, ID no servidor, license e horário.

Integrações

ox_target / qb-target

Com Config.UseTarget = true, o recurso registra uma opção de target no modelo do ped (addModel / AddTargetModel), usando label e icon do local. A opção fica indisponível se o jogador estiver em veículo, morto, com uma barra de progresso ativa ou já em processo de resgate. Todas as opções são removidas no onResourceStop.

Inventários

A entrega dos itens usa o export do inventário escolhido em Config.InventoryResource. Com qb-inventory e ps-inventory, o recurso também dispara o evento de “item box” para mostrar o pop-up de item recebido. Item inexistente gera erro no console — confira os spawn names em Config.StarterPackItems.

Combustível e chaves

Config.SetFuel e Config.GiveKey detectam o recurso em uso por GetResourceState na hora de entregar o veículo. Se o seu servidor usa um sistema fora das listas, edite essas duas funções no shared/config.lua — é o ponto de extensão previsto.

Limitações conhecidas

Herdadas do upstream, verificáveis no código:

• Veículo inicial não funciona em QBox puro. O shared/core.lua detecta o qbx_core como framework qbx, mas o spawn do veículo (client/main.lua) e a persistência em player_vehicles (server/main.lua) só tratam os ramos esx e qbc. Em um servidor com qbx_core e sem qb-core, os itens são entregues normalmente, mas o veículo não spawna. Para usar o veículo inicial, é preciso estender esses dois ramos.
• Config.CheckVersion aponta para o repositório upstream (Teezy-Core/cfx-tcd-starterpack). Como este é um fork, o aviso de “nova versão” no console pode ser ruído; desligue com Config.CheckVersion = false.

Entrypoints para outros recursos

O recurso não declara exports. O que existe são eventos de servidor que outros recursos podem disparar.

Entregar o kit

TriggerServerEvent('cfx-tcd-starterpack:Server:ClaimStarterpack', 'normal')

Disparado a partir do client. Recebe a chave de Config.StarterPackItems. O servidor recusa se o jogador já recebeu ou se não estiver dentro do receiving_radius de um local.

Resetar ou apagar o registro de um jogador

TriggerServerEvent('cfx-tcd-starterpack:Server:UpdateStarterPack', identifier, 'reset')  -- libera o kit de novo
TriggerServerEvent('cfx-tcd-starterpack:Server:UpdateStarterPack', identifier, 'delete') -- apaga a linha

O identifier é o mesmo gravado na coluna identifier da tabela. Este é o evento usado pelo menu do /checkpacks.

Consultar se o jogador já recebeu

local jaRecebeu = lib.callback.await('cfx-tcd-starterpack:CB:CheckPlayer', false)

Callback registrado no servidor e chamado do client. Cria a linha do jogador se ainda não existir e retorna se ele já recebeu o kit.

Localização

As strings são traduzidas via ox_lib locale. Os arquivos ficam em locales/:

• en.json — inglês
• pt-br.json — português do Brasil

O locale ativo é definido pela convar ox:locale no server.cfg:

setr ox:locale "pt-br"

Alguns textos ficam fora do sistema de locale e estão em inglês no código: o TextUI de aproximação (Press [E] to receive your starter pack), os títulos dos diálogos de regras/quiz/captcha e o menu do /checkpacks. Para traduzi-los, edite client/main.lua diretamente.

Estrutura de arquivos

mri_Qstarterpack/
├── client/
│   ├── main.lua              — spawn dos NPCs, target/zona de proximidade, diálogos (regras, quiz,
│   │                           captcha), animação de entrega, spawn do veículo e menu do /checkpacks
│   └── functions/
│       └── common.lua        — helpers de modelo, animação, props e criação de peds
├── server/
│   ├── main.lua              — entrega de itens, persistência do veículo, registro de recebimento,
│   │                           comandos /starterpack e /checkpacks
│   └── functions/
│       ├── common.lua        — resolução do identifier, checagem de "já recebeu", check de versão
│       ├── discordlog.lua    — configuração do webhook do Discord
│       └── sql.lua           — camada SQL (oxmysql/mysql-async/ghmattimysql) e criação da tabela
├── shared/
│   ├── config.lua            — toda a configuração: locais, itens, veículos, diálogos, comandos
│   ├── core.lua              — detecção do framework (ESX/QBCore/QBox) e validação das dependências
│   └── debug.lua             — debugPrint, ativado por Config.Debug
├── locales/
│   ├── en.json
│   └── pt-br.json
├── tcd_starterpack.sql       — schema da tabela tcd_starterpack
└── fxmanifest.lua