Installazione

Dieci minuti, e la maggior parte del tempo serve solo ad aspettare che il server si avvii. Non c’è alcun file SQL da importare e nessun secondo programma da eseguire: le tabelle si creano da sole la prima volta che la risorsa viene avviata.

Ogni passaggio qui sotto termina con come capire che ha funzionato, così non andrai mai avanti col dubbio.

Prima di iniziare

Cosa ti serve	Perché
oxmysql, attivo	Tutto ciò che il telefono ricorda vive nel tuo database
ESX, QBCore, QBox o fmLib	Rilevato automaticamente; non devi specificare quale usi
Un server FiveM degli ultimi due anni	La parte web del telefono utilizza il Node integrato nel server

Nient’altro. Nessun npm, nessun passaggio di build, nessun server web.

1. Posiziona la cartella

Inserisci mic_phone nelle tue risorse — dentro una cartella tra parentesi quadre è più ordinato:

resources/[mic]/mic_phone/

Mantieni la cartella chiamata mic_phone. Non si rompe nulla se la rinomini, ma l’indirizzo web del telefono viene costruito a partire dal nome della cartella, quindi cambierebbe anche qualsiasi riferimento ad esso.

2. Avvialo dopo le risorse su cui si appoggia

In server.cfg, sotto oxmysql e sotto il tuo framework:

ensure oxmysql
ensure es_extended        # or qb-core / qbx_core
ensure mic_phone

Ha funzionato quando la console dice, all’avvio:

[mic_phone] web: door B listening on http://0.0.0.0:30125  ·  door A at /mic_phone/web/ on the game port

Se invece vedi una riga rossa riguardante un framework, avvia mic_phone dopo il tuo framework — quasi sempre il motivo è questo.

3. Il database — nulla da fare

Il primo avvio legge sql/schema.sql e crea tutto ciò che manca. Vedrai scorrere una serie di righe CREATE TABLE IF NOT EXISTS mic_phone_…. Tutto qui.

Ha funzionato quando quelle righe compaiono una sola volta e mai più negli avvii successivi.

4. Dai ai giocatori qualcosa da aprire

Di base il telefono richiede un oggetto nell’inventario chiamato phone:

-- shared/config.lua
Config.Open = {
    RequireItem = true,
    Item        = 'phone',
    ...
}

La maggior parte delle configurazioni ESX e QB ha già quell’oggetto. Utenti ox_inventory: aggiungetelo alla vostra lista oggetti se non è presente. Stai solo facendo una prova? Imposta RequireItem = false e salta completamente questo passaggio.

Ha funzionato quando entri nel server, hai l’oggetto in tasca e F1 apre il telefono. /phone fa la stessa cosa, e T lo apre in modalità tablet mentre è aperto.

5. Impostazioni solo lato server

Copia il file di esempio e compila ciò che ti serve:

shared/server_config.example.lua  →  shared/server_config.lua

Questo file viene caricato esclusivamente come script server, quindi nulla di ciò che contiene raggiunge mai un giocatore. Al suo interno vivono due cose:

Foto, video e note vocali. Inserisci un token media di Fivemanage in ServerConfig.Media.Token (oppure nella convar FIVEMANAGE_MEDIA_API_KEY) e il telefono caricherà i file autonomamente, salvando solo il link risultante. Un webhook Discord funziona come alternativa.

Se non ne imposti nessuno, FallbackToDataUrl salva il file dentro il tuo database. Va bene per un test, ma è pesante in produzione: pochi secondi di voce occupano decine di kilobyte su ogni riga coinvolta. Imposta un token oppure disattiva quell’opzione e lascia che i caricamenti falliscano esplicitamente.

Webhook Discord. Un URL per ogni tipo di evento, oppure Default per raccogliere tutto. Quello che vale la pena impostare anche se ignori il resto è Server: è l’unico che ti informa sul server anziché su un giocatore — ad esempio se l’indirizzo è cambiato o se un certificato non si è rinnovato.

Hai finito

Il telefono funziona. Tutto ciò che segue è opzionale.

Opzionale: il telefono su un telefono vero

I giocatori possono portare il telefono del proprio personaggio sul loro vero smartphone. È già attivo: Impostazioni › Dispositivi collegati sul telefono in gioco mostra un codice QR; basta inquadrarlo e digitare in gioco le sei cifre visualizzate. Quel dispositivo agirà quindi come quel personaggio.

Su semplice HTTP questo dà già accesso a messaggi, posta, contatti, garage, proprietà e tutto il resto. Ciò che un browser non concede a una pagina non sicura è però la parte migliore:

	HTTP semplice	HTTPS
Messaggi, posta, garage, tutto il resto	sì	sì
Notifiche con l’app chiusa	no	sì
Chiamate	no	sì
Il microfono, per le note vocali	no	sì
Installarlo come app, con la propria icona	no	sì

Ottenere HTTPS, senza installare nulla

Questa risorsa può ottenere e rinnovare da sola il proprio certificato. Fai puntare un dominio al tuo server, apri due porte e compila tre righe:

-- shared/server_config.lua  (server-only: this file is never sent to a client)
ServerConfig.Web = {
    Url = 'https://phone.yourserver.com/',
    Https = {
        Enabled = true,
        Names   = { 'phone.yourserver.com' },
        Contact = '[email protected]',
    },
}

Un nome. Su una VPS basta un record A che punta al suo indirizzo. Non hai un dominio? duckdns.org te ne dà uno gratuito in un minuto.
Porta 80 e porta 443 aperte nel firewall. La 80 viene aperta solo mentre viene richiesto il certificato e richiusa non appena arriva la risposta.

Ha funzionato quando la console dice:

https: asking for phone.yourserver.com
https: port 80 open for the challenge
https: challenge port closed
https: certificate in hand, good until 2027-01-31
https: listening on https://phone.yourserver.com/

Se la 443 è occupata — alcuni router la tengono per la propria pagina di amministrazione — usa invece un’altra porta: Port = 8443, inoltra la 8443 e scrivi Url = 'https://phone.yourserver.com:8443/'. Solo la verifica (challenge) deve passare sulla 80; un certificato appartiene a un nome, non a una porta, e tutto continuerà a funzionare.

docs/HTTPS.md copre gli altri casi: dietro il proxy Cfx.re, dietro un reverse proxy che già gestisci, o su un hosting che non ti assegna porte.

Quando qualcosa non va

phonehttps check — chiede al server di test dell’autorità di certificazione se riesce a comunicare con la tua macchina. Eseguilo per primo quando non arriva alcun certificato: distingue un problema del tuo firewall da uno di questa risorsa.

phonehttps — mostra lo stato del certificato e quando verrà rinnovato.

phoneduck — mostra lo stato del dominio, se il server mantiene aggiornato da sé il proprio nome DuckDNS, e quando lo ha comunicato l’ultima volta. phoneduck now invia l’indirizzo attuale e stampa la risposta di DuckDNS, il modo più rapido per scoprire se un token è errato senza aspettare che l’indirizzo cambi.

Cosa vedi	Cos’è
Il telefono non si apre	Manca l’oggetto `phone`, oppure `RequireItem` è attivo e il giocatore non ne ha uno con sé
Il QR punta a un indirizzo irraggiungibile	Imposta `ServerConfig.Web.Url` manualmente; il rilevamento automatico non vede oltre un router che sposta la porta
Nessun certificato, e il log dà la colpa alla challenge	La porta 80 non raggiunge questa macchina. Controlla il port forwarding e il firewall, in quest’ordine
Le foto sono enormi / il database cresce rapidamente	Nessun token media, e `FallbackToDataUrl` sta salvando i file nel database
Le chiamate tra due giocatori sono mute	La voce è su `auto` e non ha trovato alcuna risorsa vocale; indica la tua in `Config.Bridge.voice`

Prima di aprire la tua città

shared/server_config.lua è solo tuo. Non condividerlo né caricarlo mai in repository pubblici: contiene il tuo token media e gli URL dei tuoi webhook.
Fai puntare il webhook Server in un posto che leggi. È quello che ti avvisa se la porta d’ingresso web del telefono ha smesso di funzionare, ed è l’unico avviso che riceverai prima che te lo dica un giocatore.
Disattiva Config.Debug se lo avevi attivato: stampa nella console ogni decisione presa dal bridge.
Sicurezza merita dieci minuti di lettura se gestisci una città pubblica: spiega cosa dà per scontato questa risorsa riguardo a chi si connette e quali regole applica affinché un client modificato non possa andare oltre il proprio personaggio.