Questa guida copre lo sviluppo delle risorse, la configurazione del database, gli strumenti di amministrazione, la gestione dei giocatori, la gestione dei veicoli e delle armi, e la risoluzione dei problemi per il tuo server alt:V su Legion Hosting. Per la configurazione iniziale del server, la configurazione di server.toml e le istruzioni di connessione, consulta Guida alla Configurazione del Server alt:V.

---

Configurazione Admin

alt:V non dispone di un sistema admin integrato. Le funzionalità admin vengono implementate tramite risorse (script) che crei o installi. La maggior parte delle modalità di gioco implementa il proprio sistema admin con livelli di permessi, ruoli e comandi admin.

Approcci Admin Comuni

• Ruoli basati su database: La maggior parte dei framework roleplay e delle modalità di gioco memorizza i ruoli admin in un database. Agli admin vengono assegnati ruoli (es. moderatore, admin, superadmin) che concedono diversi livelli di permessi.
• Admin basati su configurazione: Le configurazioni più semplici possono utilizzare un file di configurazione che elenca gli Steam ID o gli alt:V ID degli admin con i relativi livelli di permessi.
• Comandi da console: La console del server di GPanel ha sempre accesso completo. Puoi scrivere script lato server che accettano input dalla console per le operazioni admin.

Configurazione di una Risorsa Admin

1. Scegli o sviluppa una risorsa admin adatta alla tua modalità di gioco.
2. Carica la risorsa nella directory resources/ tramite la scheda Files o SFTP.
3. Aggiungi il nome della risorsa all'array resources in server.toml.
4. Configura la risorsa admin (imposta i tuoi Steam/alt:V ID admin, livelli di permessi, ecc.).
5. Riavvia il server.

---

Sistema delle Risorse

Le risorse sono i componenti fondamentali dei server alt:V. Ogni risorsa è un modulo autonomo che può contenere codice lato server, codice lato client, o entrambi. Le risorse sono scritte in JavaScript, TypeScript o C#.

Struttura delle Risorse

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

Configurazione di resource.toml

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

Campi: type (js o csharp), main (punto di ingresso lato server), client-main (punto di ingresso lato client, eseguito nel GTA V del giocatore), client-files (file da inviare al client, supporta i glob), deps (altre risorse da caricare prima).

---

Installazione delle Risorse

Per installare una risorsa pre-costruita sul tuo server:

1. Scarica i file della risorsa (tipicamente una cartella contenente resource.toml e file di script).
2. Ferma il server in GPanel.
3. Carica la cartella della risorsa in resources/ tramite la scheda Files o SFTP.
4. Aggiungi il nome della cartella della risorsa all'array resources in server.toml:

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

5. Se la risorsa ha dipendenze, assicurati che siano anch'esse installate e elencate.
6. Configura la risorsa secondo la sua documentazione (file di configurazione, configurazione del database, ecc.).
7. Avvia il server. Controlla la console per i messaggi di caricamento delle risorse e eventuali errori.

Rimozione di una Risorsa

1. Ferma il server.
2. Rimuovi il nome della risorsa dall'array resources in server.toml.
3. Facoltativamente, elimina la cartella della risorsa da resources/.
4. Avvia il server.

---

Configurazione del Database

La maggior parte delle modalità di gioco alt:V richiede un database per memorizzare i dati dei giocatori, i veicoli, gli inventari e altre informazioni persistenti. I due sistemi di database più comuni per alt:V sono MongoDB e MySQL/MariaDB.

MongoDB

MongoDB è un database documentale NoSQL comunemente usato con le risorse JavaScript/TypeScript. Utilizza un servizio gestito come MongoDB Atlas (livello gratuito disponibile) o un'istanza self-hosted. Ottieni la tua stringa di connessione (es. mongodb+srv://user:[email protected]/mydb) e configurala nel file di configurazione della tua risorsa. Le risorse Node.js utilizzano il pacchetto npm mongodb.

MySQL / MariaDB

MySQL è comunemente usato con le risorse C# e alcuni framework JavaScript. Ottieni un database da un servizio gestito o un'istanza self-hosted, configura le tue risorse con i dettagli di connessione (host, porta, nome utente, password, nome del database) ed esegui gli script di migrazione SQL necessari.

---

Gestione dei Giocatori

La gestione dei giocatori in alt:V viene gestita tramite le tue risorse. Le operazioni comuni includono:

Identificazione dei Giocatori

alt:V fornisce diversi identificatori per ogni giocatore connesso:

Espulsione e Ban

Implementa le funzionalità di espulsione e ban nelle tue risorse:

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

---

Gestione di Veicoli e Armi

I veicoli e le armi vengono gestiti tramite script lato server. alt:V ti offre il pieno controllo sulla creazione, modifica e rimozione di veicoli e armi.

Creazione di Veicoli

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

Assegnazione di Armi

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

// Remove all weapons
player.removeAllWeapons();

Persistenza dei Veicoli

Per impostazione predefinita, i veicoli esistono solo nella memoria del server e vengono persi al riavvio. Per rendere i veicoli persistenti tra i riavvii, memorizza i loro dati (modello, posizione, modifiche, proprietario) in un database e ricreali all'avvio del server.

---

Risoluzione dei Problemi

Le Risorse Non si Caricano

• Verifica che il nome della risorsa in server.toml corrisponda esattamente al nome della cartella in resources/.
• Verifica che la risorsa abbia un file resource.toml valido con i campi type e main corretti.
• Controlla la console per i messaggi di errore durante il caricamento delle risorse. Gli errori di sintassi negli script impediranno l'avvio della risorsa.
• Assicurati che tutte le dipendenze elencate in deps siano installate e caricate.
• Verifica che il modulo corretto sia caricato in server.toml (js-module per JavaScript, csharp-module per C#).

I Giocatori Non Riescono a Connettersi

• Verifica che il server sia in esecuzione e risulti online in GPanel.
• Controlla che i giocatori stiano usando il launcher alt:V, non il launcher normale di GTA V.
• Assicurati che il branch del server alt:V corrisponda a quello dei giocatori (release, rc o dev). Branch non corrispondenti impediscono le connessioni.
• Se protetto da password, verifica che i giocatori stiano inserendo la password corretta.
• Fai provare ai giocatori la connessione diretta con IP e porta. Consulta Come Trovare l'IP e la Porta del Tuo Server.

Crash del Server

• Controlla la console per i messaggi di errore prima del crash.
• Le risorse difettose sono la causa più comune dei crash. Disabilita le risorse aggiunte di recente per isolare il problema.
• Assicurati che i file del server siano aggiornati. Attiva una reinstallazione dalla scheda Startup se necessario.
• Le perdite di memoria nelle risorse possono causare l'esaurimento della RAM del server nel tempo. Monitora i grafici delle risorse di GPanel per un utilizzo della memoria in costante aumento.

Problemi con Database e Chat Vocale

• Verifica le credenziali del database e le stringhe di connessione. Per MongoDB Atlas, aggiungi l'IP del tuo server alla whitelist nelle impostazioni di accesso di rete.
• Controlla la console per i messaggi di errore di connessione al database.
• La chat vocale richiede la sezione [voice] in server.toml più risorse che implementano la logica dei canali vocali. La configurazione da sola imposta solo l'infrastruttura.

Problemi di Prestazioni

• Analizza le tue risorse alla ricerca di operazioni costose (cicli pesanti, chiamate database sincrone, creazione eccessiva di entità).
• Usa alt.setInterval e alt.setTimeout con parsimonia. Le operazioni pesanti per ogni tick sono la causa più comune di problemi di prestazioni.
• Monitora i grafici delle risorse di GPanel per l'utilizzo di CPU e RAM.
• Considera l'upgrade del tuo piano server per un elevato numero di giocatori. Apri un ticket di supporto per discutere le opzioni.

---

Articoli Correlati

• Guida alla Configurazione del Server alt:V — Configurazione iniziale, configurazione server.toml, chat vocale e istruzioni di connessione
• Come Trovare l'IP e la Porta del Tuo Server
• Come Caricare File via SFTP
• Guida all'Avvio del Server — Guida generale per avviare qualsiasi server di gioco su Legion Hosting

---

Hai Bisogno di Ulteriore Aiuto?

Se riscontri problemi non trattati in questa guida, il nostro team di supporto è disponibile ad assisterti. Apri un ticket su legionhosting.net/submitticket.php con i dettagli del tuo server, una descrizione del problema e qualsiasi messaggio di errore rilevante dalla console di GPanel.