Este guia cobre desenvolvimento de resources, configuração de banco de dados, ferramentas de administração, gerenciamento de jogadores, gerenciamento de veículos e armas, e solução de problemas para seu servidor alt:V na Legion Hosting. Para configuração inicial do servidor, configuração do server.toml e instruções de conexão, veja Guia de Configuração do Servidor alt:V.

---

Configuração de Admin

O alt:V não possui um sistema de admin integrado. A funcionalidade de admin é implementada através de resources (scripts) que você cria ou instala. A maioria dos gamemodes implementa seu próprio sistema de admin com níveis de permissão, cargos e comandos de administração.

Abordagens Comuns de Admin

• Cargos baseados em banco de dados: A maioria dos frameworks de roleplay e gamemode armazena cargos de admin em um banco de dados. Os admins recebem cargos (ex.: moderador, admin, superadmin) que concedem diferentes níveis de permissão.
• Admins baseados em configuração: Configurações mais simples podem usar um arquivo de configuração listando Steam IDs ou alt:V IDs dos admins com seus níveis de permissão.
• Comandos de console: O console do servidor no GPanel sempre tem acesso total. Você pode criar scripts server-side que aceitam entrada do console para operações de administração.

Configurando um Resource de Admin

1. Escolha ou desenvolva um resource de admin que se encaixe no seu gamemode.
2. Envie o resource para o diretório resources/ via aba Files ou SFTP.
3. Adicione o nome do resource ao array resources no server.toml.
4. Configure o resource de admin (defina seus Steam/alt:V IDs de admin, níveis de permissão, etc.).
5. Reinicie o servidor.

---

Sistema de Resources

Resources são os blocos de construção fundamentais dos servidores alt:V. Cada resource é um módulo independente que pode conter código server-side, código client-side, ou ambos. Resources são escritos em JavaScript, TypeScript ou C#.

Estrutura de um Resource

resources/
  my-resource/
    resource.toml         <-- Resource configuration (required)
    server/
      index.js            <-- Server-side entry point
      utils.js            <-- Additional server-side files
    client/
      index.js            <-- Client-side entry point (runs in player's GTA V)
    shared/
      config.js           <-- Shared code accessible by both server and client

Configuração do resource.toml

type = "js"
main = "server/index.js"
client-main = "client/index.js"
client-files = ["client/*"]
deps = ["chat"]

Campos: type (js ou csharp), main (ponto de entrada server-side), client-main (ponto de entrada client-side, executa no GTA V do jogador), client-files (arquivos para enviar ao client, suporta globs), deps (outros resources para carregar primeiro).

---

Instalando Resources

Para instalar um resource pré-construído no seu servidor:

1. Baixe os arquivos do resource (tipicamente uma pasta contendo resource.toml e arquivos de script).
2. Pare seu servidor no GPanel.
3. Envie a pasta do resource para resources/ via aba Files ou SFTP.
4. Adicione o nome da pasta do resource ao array resources no server.toml:

resources = ["existing-resource", "new-resource"]

5. Se o resource tiver dependências, certifique-se de que elas também estejam instaladas e listadas.
6. Configure o resource de acordo com sua documentação (arquivos de configuração, configuração de banco de dados, etc.).
7. Inicie o servidor. Verifique o console para mensagens de carregamento de resources e quaisquer erros.

Removendo um Resource

1. Pare seu servidor.
2. Remova o nome do resource do array resources no server.toml.
3. Opcionalmente, exclua a pasta do resource de resources/.
4. Inicie o servidor.

---

Configuração de Banco de Dados

A maioria dos gamemodes alt:V requer um banco de dados para armazenar dados de jogadores, veículos, inventários e outras informações persistentes. Os dois sistemas de banco de dados mais comuns para alt:V são MongoDB e MySQL/MariaDB.

MongoDB

MongoDB é um banco de dados de documentos NoSQL comumente usado com resources JavaScript/TypeScript. Use um serviço gerenciado como MongoDB Atlas (plano gratuito disponível) ou uma instância auto-hospedada. Obtenha sua string de conexão (ex.: mongodb+srv://user:[email protected]/mydb) e configure-a no arquivo de configuração do seu resource. Resources Node.js usam o pacote npm mongodb.

MySQL / MariaDB

MySQL é comumente usado com resources C# e alguns frameworks JavaScript. Obtenha um banco de dados de um serviço gerenciado ou instância auto-hospedada, configure seus resources com os detalhes de conexão (host, porta, usuário, senha, nome do banco de dados) e execute quaisquer scripts de migração SQL necessários.

---

Gerenciamento de Jogadores

O gerenciamento de jogadores no alt:V é feito através dos seus resources. Operações comuns incluem:

Identificando Jogadores

O alt:V fornece vários identificadores para cada jogador conectado:

Expulsão e Banimento

Implemente funcionalidades de expulsão e banimento nos seus resources:

import alt from "alt-server";

// Kick a player
player.kick("Reason for kick");

// Ban check on connect (store bans in database)
alt.on("playerConnect", (player) => {
    if (isPlayerBanned(player.socialID)) {
        player.kick("You are banned from this server.");
    }
});

---

Gerenciamento de Veículos e Armas

Veículos e armas são gerenciados através de scripts server-side. O alt:V oferece controle total sobre criação, modificação e remoção de veículos e armas.

Criando Veículos

import alt from "alt-server";

// Spawn a vehicle at a position
const vehicle = new alt.Vehicle(
    "sultan",            // Vehicle model name
    0, 0, 72,           // Position (x, y, z)
    0, 0, 0             // Rotation (rx, ry, rz)
);
vehicle.numberPlateText = "LEGION";

Dando Armas

// Give a weapon to a player
player.giveWeapon(alt.hash("weapon_pistol"), 100, true);

// Remove all weapons
player.removeAllWeapons();

Persistência de Veículos

Por padrão, veículos existem apenas na memória do servidor e são perdidos ao reiniciar. Para persistir veículos entre reinicializações, armazene seus dados (modelo, posição, modificações, proprietário) em um banco de dados e recrie-os ao iniciar o servidor.

---

Solução de Problemas

Resources Não Carregam

• Verifique se o nome do resource no server.toml corresponde exatamente ao nome da pasta em resources/.
• Verifique se o resource possui um arquivo resource.toml válido com os campos type e main corretos.
• Verifique o console para mensagens de erro durante o carregamento do resource. Erros de sintaxe nos scripts impedirão o resource de iniciar.
• Certifique-se de que todas as dependências listadas em deps estejam instaladas e carregadas.
• Verifique se o módulo correto está carregado no server.toml (js-module para JavaScript, csharp-module para C#).

Jogadores Não Conseguem Conectar

• Verifique se o servidor está rodando e aparecendo como online no GPanel.
• Verifique se os jogadores estão usando o launcher alt:V, não o launcher regular do GTA V.
• Certifique-se de que a branch do servidor alt:V corresponde à dos jogadores (release, rc ou dev). Branches incompatíveis impedem conexões.
• Se protegido por senha, verifique se os jogadores estão inserindo a senha correta.
• Peça aos jogadores para tentar conexão direta com o IP e porta. Veja Como Encontrar o IP e Porta do Seu Servidor.

Servidor Travando

• Verifique o console para mensagens de erro antes do travamento.
• Resources com falhas são a causa mais comum de travamentos. Desative resources adicionados recentemente para isolar o problema.
• Certifique-se de que os arquivos do servidor estão atualizados. Acione uma reinstalação na aba Startup se necessário.
• Vazamentos de memória em resources podem fazer o servidor ficar sem RAM ao longo do tempo. Monitore os gráficos de recursos do GPanel para uso de memória aumentando constantemente.

Problemas de Banco de Dados e Voz

• Verifique as credenciais do banco de dados e strings de conexão. Para MongoDB Atlas, adicione o IP do seu servidor à lista de permissões nas configurações de acesso à rede.
• Verifique o console para mensagens de erro de conexão com o banco de dados.
• O chat de voz requer a seção [voice] no server.toml além de resources que implementem a lógica de canais de voz. A configuração sozinha apenas configura a infraestrutura.

Problemas de Desempenho

• Analise seus resources em busca de operações custosas (loops pesados, chamadas síncronas ao banco de dados, criação excessiva de entidades).
• Use alt.setInterval e alt.setTimeout com moderação. Operações pesadas por tick são o maior causador de problemas de desempenho.
• Monitore os gráficos de recursos do GPanel para uso de CPU e RAM.
• Considere fazer upgrade do plano do seu servidor para contagens altas de jogadores. Abra um ticket de suporte para discutir opções.

---

Artigos Relacionados

• Guia de Configuração do Servidor alt:V — Configuração inicial, configuração do server.toml, chat de voz e instruções de conexão
• Como Encontrar o IP e Porta do Seu Servidor
• Como Enviar Arquivos via SFTP
• Guia de Início do Servidor — Guia geral para iniciar qualquer servidor de jogo na Legion Hosting

---

Precisa de Mais Ajuda?

Se você está enfrentando problemas não cobertos neste guia, nossa equipe de suporte está disponível para ajudar. Abra um ticket em legionhosting.net/submitticket.php com os detalhes do seu servidor, uma descrição do problema e quaisquer mensagens de erro relevantes do console do GPanel.