> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dkscripts.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros e Soluções

> Guia de solução de problemas comuns do dk_skinshop

# 🔧 Erros e Soluções

Encontrou um problema? Comece pela mensagem que apareceu na tela ou no console — ela quase sempre está listada abaixo.

<Tip>
  **Antes de qualquer coisa:** ligue o `debugMode` do lado afetado.

  * `config/client/config.lua` → mensagens no console **F8** do jogador
  * `config/server/config.lua` → mensagens no console do **servidor**

  Volte para `false` depois do teste.
</Tip>

***

## 🔐 Instalação e autenticação

<AccordionGroup>
  <Accordion title="O recurso não inicia e acusa falta de dk_snippets" icon="puzzle-piece" defaultOpen>
    ### Problema

    O console reclama do `dk_snippets` ao iniciar o recurso.

    ### Solução

    O `dk_snippets` é dependência do manifesto e também é carregado por `@dk_snippets/init.lua`.

    <Steps>
      <Step title="Confirme o nome da pasta">
        Precisa ser exatamente `dk_snippets`.
      </Step>

      <Step title="Confirme a ordem de start">
        Ele precisa iniciar **antes** do `dk_skinshop`.
      </Step>

      <Step title="Confirme o nome da pasta do skinshop">
        A pasta instalada precisa se chamar exatamente `dk_skinshop` — o nome aparece nos `require`, exports, eventos e caminhos da interface.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Erro: Script não autenticado" icon="lock">
    ### Problema

    O console mostra que o script não foi autenticado, ou aparece a mensagem **"Loja indisponível: recurso não autenticado"**.

    ### Causas possíveis

    * IP do servidor não cadastrado na licença
    * `license.lua` removido ou substituído
    * Licença expirada ou inválida

    ### Soluções

    <Steps>
      <Step title="Verifique o license.lua">
        Ele veio junto do produto e precisa continuar na raiz do recurso.
      </Step>

      <Step title="Verifique o IP">
        Confirme se o IP atual do servidor está cadastrado na licença.
      </Step>

      <Step title="Altere o IP">
        Acesse a sala **💻・comandos** no Discord e use o comando para alterar o IP.
      </Step>

      <Step title="Reinicie o servidor">
        Depois de alterar o IP, reinicie completamente o servidor.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="A loja abriu em uma versão reduzida" icon="triangle-exclamation">
    ### Problema

    A loja abre com uma tela simples: troca de peça e cor por setas, sem fotos, sem compra, sem outfits e sem guarda-roupa.

    ### Causa

    É o **modo de desenvolvimento**, usado enquanto a licença ainda não foi validada e `devShop.enabled = true`.

    ### Solução

    Resolva a autenticação (acima). Assim que a licença valida, a loja completa assume sozinha e o comando `/skinshopdev` para de responder.

    <Note>
      Com `devShop.enabled = false`, a loja simplesmente **não abre** até a autenticação terminar.
    </Note>
  </Accordion>

  <Accordion title="As tabelas não foram criadas no banco" icon="database">
    ### Problema

    Nada é salvo e o console reclama de acesso ao banco.

    ### Solução

    O recurso cria as tabelas sozinho — desde que o driver de banco esteja rodando **antes** dele.

    ```cfg theme={null}
    ensure oxmysql
    ensure [dk]
    ```

    <Warning>
      Se o driver de banco também estiver dentro de `[dk]`, coloque-o antes do `dk_snippets` na ordem de start da pasta, ou inicie-o separadamente antes dela.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## 👕 Roupas e armazenamento

<AccordionGroup>
  <Accordion title="A roupa não salva ou não volta quando o jogador entra" icon="floppy-disk" defaultOpen>
    ### Diagnóstico

    Procure no console do servidor a linha que aparece no boot:

    ```
    [dk_skinshop] Storage de roupas: vrp.playerdata
    ```

    Ela informa **onde** a roupa está sendo gravada.

    ### Soluções

    <Steps>
      <Step title="Confirme se o adapter é o certo">
        Se a detecção automática pegou um schema errado, force o correto ou use `clothesStorage = "script"`.
      </Step>

      <Step title="Confirme se o jogador tem uma base">
        No ESX, ele precisa de uma skin em `users.skin`. No QB/Qbox, de uma skin ativa em `playerskins`.
      </Step>

      <Step title="Confirme o carregamento no spawn">
        `loadClothesOnSpawn.enabled` precisa estar `true`.
      </Step>

      <Step title="Spawn customizado?">
        Adicione o nome do evento em `loadClothesOnSpawn.events`.
      </Step>
    </Steps>

    <Card title="Armazenamento das Roupas" icon="database" href="/scripts/skinshop/configs/clothes-storage" horizontal>
      A lista de adapters, a ordem de detecção e as ressalvas por framework.
    </Card>
  </Accordion>

  <Accordion title="A roupa é sobrescrita logo depois de salvar" icon="rotate">
    ### Causa mais comum

    O **vRPex** mantém o datatable em memória enquanto o jogador está online e pode sobrescrever a gravação direta no próximo save.

    ### Solução

    Use `clothesStorage = "script"` para isolar o armazenamento do skinshop.
  </Accordion>

  <Accordion title="Duas roupas diferentes sendo aplicadas no login" icon="clone">
    ### Causa

    Outro script de skin ainda está ativo e disputando o ped.

    ### Solução

    Pare o script antigo de roupas. Se ele precisa continuar rodando, considere `clothesStorage = "auto"` para que os dois leiam do **mesmo lugar**.
  </Accordion>
</AccordionGroup>

***

## 📸 Fotos das roupas

<AccordionGroup>
  <Accordion title="As fotos não aparecem — só os ícones de categoria" icon="image" defaultOpen>
    ### Causa

    A interface usa o ícone da categoria sempre que a foto **não carrega**. O problema está no caminho ou na hospedagem.

    ### Solução

    Abra no navegador a URL completa de uma peça, montada pelo template:

    ```
    http://SEU-ENDERECO/clothes/mp_m_freemode_01/torso/4_0.webp
    ```

    Se ela não abre no navegador, também não vai abrir na interface.

    <Steps>
      <Step title="baseUrl sem barra no final">
        O template já começa com o nome do modelo.
      </Step>

      <Step title="Extensão correta">
        O `ext` precisa bater com os arquivos gerados.
      </Step>

      <Step title="Ped cadastrado">
        Peds addon precisam estar no `knownModels` — senão o script busca as fotos do `mp_m_freemode_01`.
      </Step>

      <Step title="Nome das pastas">
        Categorias com pasta de nome diferente do id precisam estar no `categoryMap`.
      </Step>
    </Steps>

    <Card title="Fotos das Roupas" icon="image" href="/scripts/skinshop/configs/item-images" horizontal>
      Configuração completa do bloco `itemImages`.
    </Card>
  </Accordion>
</AccordionGroup>

***

## 🎮 Interface e acesso

<AccordionGroup>
  <Accordion title="Erro: Você não tem permissão para acessar este ponto" icon="ban" defaultOpen>
    ### Causa

    O ponto tem uma permissão restrita e o jogador não a possui.

    | Permissão do ponto | Quem acessa                                         |
    | ------------------ | --------------------------------------------------- |
    | **Qualquer um**    | Todos                                               |
    | **VIP**            | Quem tem a `vipPermission`. Admins também contam    |
    | **Admin**          | Apenas administradores do framework                 |
    | **Grupo**          | Quem tem uma das labels de líder ou membro do ponto |

    ### Solução

    Confira a permissão do ponto em `/ssadmin` → **Editar** e a `vipPermission` no config do servidor.
  </Accordion>

  <Accordion title="A tecla E não abre nada" icon="keyboard">
    ### Verifique

    <Steps>
      <Step title="Distância">
        O jogador precisa estar dentro do **raio de interação** do ponto.
      </Step>

      <Step title="Tecla remapeada">
        O FiveM salva a tecla no perfil do jogador. Confira em **Configurações → Controles**.
      </Step>

      <Step title="Hook bloqueando">
        Um `onBeforeOpenUi` retornando `false` impede a abertura. Confira o hook em `config/client/config.lua`.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="O comando /ssadmin não abre o painel" icon="user-shield">
    ### Causas

    * O framework não reconhece o jogador como administrador
    * O `adminCommand` está vazio no config do servidor

    ### Solução

    A checagem acontece **no servidor**. Confirme a permissão de admin no framework e o valor de `adminCommand`.
  </Accordion>

  <Accordion title="O ponto foi criado mas não aparece no mapa" icon="location-dot">
    ### Causa

    A opção **Mostrar ícone no mapa** está desligada — ou o nome do ponto ficou vazio.

    ### Nota

    O ponto **continua funcionando** normalmente: só não exibe o ícone. Se isso não era a intenção, edite o ponto em `/ssadmin`.
  </Accordion>
</AccordionGroup>

***

## 💰 Compras

<AccordionGroup>
  <Accordion title="Erro: Você não tem dinheiro suficiente para essa compra" icon="money-bill">
    O valor do carrinho é maior que o saldo do jogador. O total considera os descontos: com `purchasedDiscount` ligado, peças já compradas custam zero.
  </Accordion>

  <Accordion title="Erro: Aguarde um instante antes de comprar novamente" icon="hourglass">
    Proteção anti-spam entre compras seguidas. Basta aguardar alguns segundos.
  </Accordion>

  <Accordion title="Erro: Não foi possível concluir a compra" icon="circle-xmark">
    ### Causa comum

    Um hook `onBeforeBuy` retornando `false` no `config/server/config.lua`.

    ### Solução

    Revise o hook. Lembre que ele só cancela quando retorna **exatamente `false`**.
  </Accordion>

  <Accordion title="O valor cobrado no conjunto é maior que o preço do card" icon="tag">
    ### Causa

    O `conjuntoDiscount` altera **apenas o preço exibido no card** do conjunto. Na cobrança, o servidor soma o preço cheio de cada peça — descontando só o que o jogador já possui, via `purchasedDiscount`.

    ### Solução

    Se os dois valores precisam bater, deixe `conjuntoDiscount = 0` para o card mostrar a soma real das peças.
  </Accordion>
</AccordionGroup>

***

## ⌨️ Comandos de roupa

<AccordionGroup>
  <Accordion title="Um comando de categoria desapareceu" icon="terminal">
    ### Causa

    Os comandos saem do bloco `categories` em `config/shared/config.lua`.

    | Situação                | Resultado                           |
    | ----------------------- | ----------------------------------- |
    | Categoria removida      | O comando some junto                |
    | `command = ""`          | Só o comando é desativado           |
    | Campo `command` ausente | O script gera um a partir do `name` |
  </Accordion>

  <Accordion title="Erro: Variação inválida para esta peça" icon="hashtag">
    O número informado não existe para essa categoria no modelo de ped atual. Use a loja para descobrir os números disponíveis, ou o `/lroupas` para copiar os comandos do que já está vestido.
  </Accordion>

  <Accordion title="O comando não responde quando usado várias vezes seguidas" icon="hourglass-half">
    Há **1 segundo de intervalo** entre usos do comando da **mesma** categoria. Trocar o look inteiro de uma vez (`/jaqueta 31`, `/calca 24`, `/sapatos 1`) continua funcionando, porque o intervalo é contado por categoria.
  </Accordion>
</AccordionGroup>

***

## 🤝 Compartilhamento

<AccordionGroup>
  <Accordion title="Erro: Nenhum jogador próximo encontrado" icon="users-slash">
    Só entram na lista jogadores a até **5 metros**. Aproxime-se e tente de novo.
  </Accordion>

  <Accordion title="Erro: Essa roupa não serve — o personagem tem outro corpo" icon="person-half-dress">
    Os dois personagens precisam usar o **mesmo modelo de ped**. Uma roupa masculina não encaixa em um ped feminino, e o script avisa em vez de aplicar algo quebrado.
  </Accordion>

  <Accordion title="O pedido some antes de o jogador responder" icon="clock">
    Com a interface fechada, o destinatário tem **20 segundos** para aceitar ou recusar. Depois disso o pedido expira e precisa ser reenviado.
  </Accordion>

  <Accordion title="O compartilhamento não acontece e nenhum erro aparece" icon="ban">
    Verifique o hook `onBeforeShareOutfit` no `config/server/config.lua`. Retornando `false`, ele cancela o envio silenciosamente.
  </Accordion>
</AccordionGroup>

***

## 🛡️ Outfits de organização

<AccordionGroup>
  <Accordion title="A aba Outfits do Grupo não aparece" icon="eye-slash">
    ### Causa

    O jogador não tem nenhuma das labels cadastradas no ponto, ou o ponto não usa a permissão **Grupo**.

    ### Solução

    Edite o ponto em `/ssadmin` e confira as **Labels de Líder** e **Labels de Membro** — elas precisam bater com as permissões do seu framework.
  </Accordion>

  <Accordion title="Um membro não consegue criar outfits" icon="lock">
    É o comportamento esperado. **Só líderes** criam, editam e removem uniformes do grupo; membros consultam e usam.

    Para dar esse poder a alguém, adicione a label dele em **Labels de Líder**.
  </Accordion>

  <Accordion title="Os outfits de um ponto não aparecem em outro" icon="clone">
    Também é o comportamento esperado. Os outfits de grupo são **isolados por ponto** — cada local tem a própria coleção, mesmo com as mesmas labels de acesso.
  </Accordion>

  <Accordion title="Erro: Adicione ao menos uma label de líder e uma de membro" icon="tags">
    Um ponto com permissão **Grupo** exige pelo menos uma label de cada tipo para ser salvo.
  </Accordion>
</AccordionGroup>

***

## 🔍 Ainda não resolveu?

<Steps>
  <Step title="Ligue o debugMode">
    No lado afetado — client para problemas de interface e ped, server para permissões, compras e banco.
  </Step>

  <Step title="Reproduza o problema">
    Guarde o que aparece no console F8 e no console do servidor.
  </Step>

  <Step title="Abra um ticket">
    Envie os logs junto com a versão do framework e a linha **Storage de roupas** do boot.
  </Step>
</Steps>

<Card title="Precisa de ajuda?" icon="life-ring" href="https://dkscripts.com.br/discord">
  Abra um ticket no nosso Discord para suporte técnico.
</Card>