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

---

Configuração de Admin

O alt:V não possui um sistema de administração integrado. A funcionalidade de admin é implementada através de resources (scripts) que cria ou instala. A maioria dos gamemodes implementa o 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 base de dados: A maioria dos frameworks de roleplay e gamemode armazena cargos de admin numa base de dados. Os admins recebem cargos (por exemplo, moderador, admin, superadmin) que concedem diferentes níveis de permissão.
• Admins baseados em configuração: Configurações mais simples podem usar um ficheiro de configuração listando os Steam IDs ou alt:V IDs dos admins com os seus níveis de permissão.
• Comandos de consola: A consola do servidor no GPanel tem sempre acesso total. Pode escrever scripts do lado do servidor que aceitam entrada da consola para operações de administração.

Configurar um Resource de Admin

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

---

Sistema de Resources

Os resources são os blocos de construção fundamentais dos servidores alt:V. Cada resource é um módulo independente que pode conter código do lado do servidor, código do lado do cliente, ou ambos. Os 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 do lado do servidor), client-main (ponto de entrada do lado do cliente, executado no GTA V do jogador), client-files (ficheiros a enviar para o cliente, suporta globs), deps (outros resources a carregar primeiro).

---

Instalar Resources

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

1. Descarregue os ficheiros do resource (normalmente uma pasta contendo resource.toml e ficheiros de script).
2. Pare o seu servidor no GPanel.
3. Envie a pasta do resource para resources/ através do separador 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 estas também estão instaladas e listadas.
6. Configure o resource de acordo com a sua documentação (ficheiros de configuração, configuração de base de dados, etc.).
7. Inicie o servidor. Verifique a consola para mensagens de carregamento de resources e quaisquer erros.

Remover um Resource

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

---

Configuração da Base de Dados

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

MongoDB

O MongoDB é uma base de dados NoSQL de documentos comummente usada com resources JavaScript/TypeScript. Use um serviço gerido como o MongoDB Atlas (nível gratuito disponível) ou uma instância auto-hospedada. Obtenha a sua string de conexão (por exemplo, mongodb+srv://user:[email protected]/mydb) e configure-a no ficheiro de configuração do seu resource. Os resources Node.js usam o pacote npm mongodb.

MySQL / MariaDB

O MySQL é comummente usado com resources C# e alguns frameworks JavaScript. Obtenha uma base de dados de um serviço gerido ou instância auto-hospedada, configure os seus resources com os detalhes de conexão (host, port, nome de utilizador, palavra-passe, nome da base de dados) e execute quaisquer scripts de migração SQL necessários.

---

Gestão de Jogadores

A gestão de jogadores no alt:V é feita através dos seus resources. As operações comuns incluem:

Identificar Jogadores

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

Expulsar e Banir

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.");
    }
});

---

Gestão de Veículos e Armas

Os veículos e armas são geridos através de scripts do lado do servidor. O alt:V dá-lhe controlo total sobre a criação, modificação e remoção de veículos e armas.

Criar 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";

Dar 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 predefinição, os veículos existem apenas na memória do servidor e são perdidos ao reiniciar. Para persistir veículos entre reinícios, armazene os seus dados (modelo, posição, modificações, proprietário) numa base de dados e recrie-os ao iniciar o servidor.

---

Resoluçã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 tem um ficheiro resource.toml válido com os campos type e main corretos.
• Verifique a consola 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 estão 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á em execução e aparece como online no GPanel.
• Verifique se os jogadores estão a usar o launcher alt:V, e não o launcher normal do GTA V.
• Certifique-se de que o branch do servidor alt:V corresponde ao que os jogadores têm (release, rc ou dev). Branches incompatíveis impedem conexões.
• Se protegido por palavra-passe, verifique se os jogadores estão a introduzir a palavra-passe correta.
• Peça aos jogadores para tentar a conexão direta com o IP e port. Consulte Como Encontrar o IP e Port do Seu Servidor.

Crashes do Servidor

• Verifique a consola para mensagens de erro antes do crash.
• Resources com falhas são a causa mais comum de crashes. Desative resources adicionados recentemente para isolar o problema.
• Certifique-se de que os ficheiros do servidor estão atualizados. Acione uma reinstalação a partir do separador Startup se necessário.
• Fugas de memória nos resources podem fazer com que o servidor fique sem RAM ao longo do tempo. Monitorize os gráficos de recursos do GPanel para uso de memória em aumento constante.

Problemas de Base de Dados e Voz

• Verifique as credenciais da base de dados e as strings de conexão. Para o MongoDB Atlas, adicione o IP do seu servidor à lista de permissões nas definições de acesso de rede.
• Verifique a consola para mensagens de erro de conexão à base de dados.
• O chat de voz requer a secção [voice] no server.toml mais resources que implementem lógica de canais de voz. A configuração por si só apenas configura a infraestrutura.

Problemas de Desempenho

• Analise os seus resources para operações dispendiosas (loops pesados, chamadas síncronas à base de dados, criação excessiva de entidades).
• Use alt.setInterval e alt.setTimeout com moderação. Operações pesadas por tick são o problema de desempenho mais comum.
• Monitorize os gráficos de recursos do GPanel para uso de CPU e RAM.
• Considere fazer upgrade do plano do servidor para contagens elevadas 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 Port do Seu Servidor
• Como Enviar Ficheiros via SFTP
• Guia de Início do Servidor — Guia geral para iniciar qualquer servidor de jogo na Legion Hosting

---

Precisa de Mais Ajuda?

Se está a ter problemas não abordados neste guia, a nossa equipa 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 da consola do GPanel.