Aquesta guia cobreix el desenvolupament de recursos, la configuració de bases de dades, les eines d'administració, la gestió de jugadors, la gestió de vehicles i armes, i la resolució de problemes per al vostre servidor alt:V a Legion Hosting. Per a la configuració inicial del servidor, la configuració de server.toml i les instruccions de connexió, consulteu alt:V Server Setup Guide.

---

Configuració d'administrador

alt:V no té un sistema d'administració integrat. La funcionalitat d'administració s'implementa a través de recursos (scripts) que creeu o instal·leu. La majoria de modes de joc implementen el seu propi sistema d'administració amb nivells de permisos, rols i comandes d'administració.

Enfocaments comuns d'administració

• Rols basats en base de dades: La majoria de frameworks de roleplay i modes de joc emmagatzemen els rols d'administrador en una base de dades. Als administradors se'ls assignen rols (p. ex., moderador, admin, superadmin) que atorguen diferents nivells de permisos.
• Administradors basats en configuració: Les configuracions més senzilles poden utilitzar un fitxer de configuració que llista els Steam IDs o alt:V IDs dels administradors amb els seus nivells de permisos.
• Comandes de consola: La consola del servidor de GPanel sempre té accés complet. Podeu escriure scripts del costat del servidor que acceptin entrada de consola per a operacions d'administració.

Configuració d'un recurs d'administració

1. Trieu o desenvolupeu un recurs d'administració que s'adapti al vostre mode de joc.
2. Pugeu el recurs al directori resources/ a través de la pestanya Files o SFTP.
3. Afegiu el nom del recurs a l'array resources a server.toml.
4. Configureu el recurs d'administració (establiu els vostres Steam/alt:V IDs d'administrador, nivells de permisos, etc.).
5. Reinicieu el servidor.

---

Sistema de recursos

Els recursos són els blocs fonamentals dels servidors alt:V. Cada recurs és un mòdul autònom que pot contenir codi del costat del servidor, codi del costat del client, o ambdós. Els recursos s'escriuen en JavaScript, TypeScript o C#.

Estructura dels recursos

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

Configuració de resource.toml

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

Camps: type (js o csharp), main (punt d'entrada del servidor), client-main (punt d'entrada del client, s'executa al GTA V del jugador), client-files (fitxers per enviar al client, admet globs), deps (altres recursos que cal carregar primer).

---

Instal·lació de recursos

Per instal·lar un recurs preconstruït al vostre servidor:

1. Descarregueu els fitxers del recurs (normalment una carpeta que conté resource.toml i fitxers de script).
2. Atureu el vostre servidor a GPanel.
3. Pugeu la carpeta del recurs a resources/ a través de la pestanya Files o SFTP.
4. Afegiu el nom de la carpeta del recurs a l'array resources a server.toml:

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

5. Si el recurs té dependències, assegureu-vos que també estiguin instal·lades i llistades.
6. Configureu el recurs segons la seva documentació (fitxers de configuració, configuració de base de dades, etc.).
7. Inicieu el servidor. Comproveu la consola per als missatges de càrrega de recursos i qualsevol error.

Eliminació d'un recurs

1. Atureu el vostre servidor.
2. Elimineu el nom del recurs de l'array resources a server.toml.
3. Opcionalment, suprimiu la carpeta del recurs de resources/.
4. Inicieu el servidor.

---

Configuració de la base de dades

La majoria de modes de joc d'alt:V requereixen una base de dades per emmagatzemar dades dels jugadors, vehicles, inventaris i altra informació persistent. Els dos sistemes de base de dades més comuns per a alt:V són MongoDB i MySQL/MariaDB.

MongoDB

MongoDB és una base de dades de documents NoSQL comunament utilitzada amb recursos JavaScript/TypeScript. Utilitzeu un servei gestionat com MongoDB Atlas (nivell gratuït disponible) o una instància autoallotjada. Obteniu la vostra cadena de connexió (p. ex., mongodb+srv://user:[email protected]/mydb) i configureu-la al fitxer de configuració del vostre recurs. Els recursos Node.js utilitzen el paquet npm mongodb.

MySQL / MariaDB

MySQL s'utilitza comunament amb recursos C# i alguns frameworks JavaScript. Obteniu una base de dades d'un servei gestionat o una instància autoallotjada, configureu els vostres recursos amb els detalls de connexió (host, port, nom d'usuari, contrasenya, nom de la base de dades) i executeu els scripts de migració SQL necessaris.

---

Gestió de jugadors

La gestió de jugadors a alt:V es fa a través dels vostres recursos. Les operacions comunes inclouen:

Identificació de jugadors

alt:V proporciona diversos identificadors per a cada jugador connectat:

Expulsió i ban

Implementeu la funcionalitat d'expulsió i ban als vostres recursos:

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

---

Gestió de vehicles i armes

Els vehicles i les armes es gestionen a través de scripts del costat del servidor. alt:V us dona control total sobre la generació, modificació i eliminació de vehicles i armes.

Generació de vehicles

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

Donar armes

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

// Remove all weapons
player.removeAllWeapons();

Persistència de vehicles

Per defecte, els vehicles existeixen només a la memòria del servidor i es perden en reiniciar. Per persistir els vehicles entre reinicis, emmagatzemeu les seves dades (model, posició, modificacions, propietari) en una base de dades i recreeu-los en iniciar el servidor.

---

Resolució de problemes

Els recursos no es carreguen

• Comproveu que el nom del recurs a server.toml coincideix exactament amb el nom de la carpeta a resources/.
• Verifiqueu que el recurs té un fitxer resource.toml vàlid amb els camps type i main correctes.
• Comproveu la consola per a missatges d'error durant la càrrega de recursos. Els errors de sintaxi als scripts impediran que el recurs s'iniciï.
• Assegureu-vos que totes les dependències llistades a deps estan instal·lades i carregades.
• Verifiqueu que el mòdul correcte està carregat a server.toml (js-module per a JavaScript, csharp-module per a C#).

Els jugadors no poden connectar-se

• Verifiqueu que el servidor està en funcionament i es mostra com a en línia a GPanel.
• Comproveu que els jugadors estan utilitzant el llançador alt:V, no el llançador habitual de GTA V.
• Assegureu-vos que la branca del servidor alt:V coincideix amb la que tenen els jugadors (release, rc o dev). Les branques no coincidents impedeixen les connexions.
• Si està protegit amb contrasenya, verifiqueu que els jugadors estan introduint la contrasenya correcta.
• Feu que els jugadors provin la connexió directa amb la IP i el port. Consulteu How to Find Your Server IP and Port.

Caigudes del servidor

• Comproveu la consola per a missatges d'error abans de la caiguda.
• Els recursos defectuosos són la causa més comuna de caigudes. Desactiveu els recursos afegits recentment per aïllar el problema.
• Assegureu-vos que els fitxers del vostre servidor estan actualitzats. Activeu una reinstal·lació des de la pestanya Startup si cal.
• Les fuites de memòria als recursos poden fer que el servidor es quedi sense RAM amb el temps. Monitoritzeu els gràfics de recursos de GPanel per a un ús de memòria en augment constant.

Problemes de base de dades i veu

• Verifiqueu les credencials de la base de dades i les cadenes de connexió. Per a MongoDB Atlas, afegiu la IP del vostre servidor a la llista blanca a la configuració d'accés de xarxa.
• Comproveu la consola per a missatges d'error de connexió a la base de dades.
• El xat de veu requereix la secció [voice] a server.toml més recursos que implementin la lògica de canals de veu. La configuració sola només estableix la infraestructura.

Problemes de rendiment

• Perfileu els vostres recursos per a operacions costoses (bucles pesants, crides síncrones a la base de dades, creació excessiva d'entitats).
• Utilitzeu alt.setInterval i alt.setTimeout amb moderació. Les operacions pesants per tick són el factor més comú de pèrdua de rendiment.
• Monitoritzeu els gràfics de recursos de GPanel per a l'ús de CPU i RAM.
• Considereu actualitzar el vostre pla de servidor per a recomptes elevats de jugadors. Obriu un tiquet de suport per discutir les opcions.

---

Articles relacionats

• alt:V Server Setup Guide — Configuració inicial, configuració de server.toml, xat de veu i instruccions de connexió
• How to Find Your Server IP and Port
• How to Upload Files via SFTP
• Server Startup Guide — Guia general per iniciar qualsevol servidor de joc a Legion Hosting

---

Necessiteu més ajuda?

Si teniu problemes no coberts en aquesta guia, el nostre equip de suport està disponible per ajudar-vos. Obriu un tiquet a legionhosting.net/submitticket.php amb els detalls del vostre servidor, una descripció del problema i qualsevol missatge d'error rellevant de la consola de GPanel.