Una whitelist in FiveM è un meccanismo di controllo degli accessi che limita l'accesso al server ai giocatori pre-approvati, identificati tramite i loro identificativi univoci (licenza Rockstar, ID Steam, ID Discord, ecc.). Di seguito è riportata una guida pronta per la produzione che copre la whitelist integrata di txAdmin, i pattern di script, l'archiviazione del database e le note sull'affidabilità.
TL;DR Matrice delle opzioni
| Modalità | Dove impostare | Cosa controlla | Ideale per | Note |
|---|---|---|---|---|
| Licenza approvata | txAdmin → Impostazioni → Gestione giocatori → Modalità whitelist | license: (Rockstar) | La maggior parte dei server | Semplice, affidabile; supporta approvazioni manuali o pre-approvazioni |
| Membro di Discord | txAdmin (collegato a Discord) | discord: è membro della gilda | Comunità incentrate su Discord | Utenti non Discord bloccati |
| Ruolo di Discord | txAdmin (collegato a Discord) | discord: ha un ruolo specifico | Accesso basato sui ruoli (donatore, personale) | Combina con le automazioni dei ruoli |
| Solo amministratore | txAdmin | Solo amministratori | Notti di manutenzione/sviluppo | Blocca efficacemente il server, non consigliato |
| Script personalizzato | Risorsa Lua/JS | Tutti gli identificatori che desideri | Regole granulari e UX | Necessita di codice + manutenzione |
Raccomandazione: Utilizzo Licenza approvata per la base (tutti hanno una licenza Rockstar), quindi aggiungi Ruolo di Discord come cancello aggiuntivo per livelli speciali.
Come abilitare e utilizzare la whitelist in txAdmin
Prerequisiti
- txAdmin in esecuzione (fornito con FXServer).
- Per le modalità Discord: integrazione Discord configurata (bot invitato, gilda/ruolo selezionato).
Abilita la whitelist
- Aprire txAdmin → Impostazioni → Gestione giocatori.
- Impostato Modalità Whitelist a uno di: Licenza approvata, Membro di Discord, Ruolo di Discord, O Solo amministratore.
- Imposta un Messaggio di rifiuto, per esempio:
Not whitelisted. Apply at discord.gg/yourinvite - Salva.
Approva i giocatori (due flussi)
- Passivo (coda): Quando un giocatore non approvato tenta di unirsi, viene visualizzata una richiesta sotto Lista biancaApprova/rifiuta con un clic.
- Attivo (pre-approvazione): Vai a Whitelist → Aggiungi approvazione e incolla un identificatore nel modulo
type:value, per esempiolicense:110000112345678steam:11000010abcdef0discord:123456789012345678
Revocare
- Aprire Giocatori O Lista bianca e clicca Revocare accanto all'approvazione.
Suggerimenti
- Prefer licenza identificatori per l'accesso di base (universalmente presenti).
- Mantieni il tuo messaggio di rifiuto attuabile (link Discord + regole di base + CTA del ticket).
- Per il personale/sviluppatori, requisiti di stack: ad esempio, deve essere
license+discord role.
Dettagli di implementazione tecnica
Le whitelist vengono eseguite durante differimento della connessione Fase. Il server esamina l'identificativo del giocatore e accetta o rifiuta prima del caricamento delle risorse. Questo mantiene basso il carico e blocca in anticipo i giocatori non approvati.
Tipi di identificatori (affidabilità)
license:(Rockstar) — stabile, legato all'acquisto del gioco; chiave primaria consigliata.steam:— presente solo se Steam è in esecuzione; può mancare se i giocatori non utilizzano Steam.discord:— presente solo se Discord è in esecuzione e il tuo server lo legge.ip:— dinamico; da utilizzare per telemetria/limite di velocità, non per l'identità.
Script minimo di whitelist (differimenti UX + multi-ID)
-- resource: simple-whitelist
-- fxmanifest.lua should include '@oxmysql/lib/MySQL.lua' if you use DB code below.
local STATIC_WHITELIST = {
["license:110000112345678"] = true,
["steam:11000010abcdef0"] = true,
["discord:123456789012345678"] = true,
}
local function collectIdentifiers(src)
local ids = {}
for _, id in ipairs(GetPlayerIdentifiers(src)) do ids[id] = true end
return ids
end
AddEventHandler("playerConnecting", function(name, setKickReason, deferrals)
local src = source
deferrals.defer()
deferrals.update(("Checking whitelist for %s..."):format(name))
local ids = collectIdentifiers(src)
-- Require at least a Rockstar license in all cases
local hasLicense = false
for id, _ in pairs(ids) do
if id:sub(1, 8) == "license:" then hasLicense = true break end
end
if not hasLicense then
return deferrals.done("You must start the game normally (Rockstar license missing). Restart and try again.")
end
-- Static allowlist quick‑path
for id, _ in pairs(ids) do
if STATIC_WHITELIST[id] then
return deferrals.done()
end
end
-- Fallback: not approved
return deferrals.done("Not whitelisted. Apply at discord.gg/yourinvite")
end)
Utilizzo rinvii.aggiornamento per mostrare messaggi di avanzamento durante il controllo degli ID e/o di un database. Questo riduce i falsi report di "timeout".
Whitelist basata su database (oxmysql, pronta per la produzione)
Schema
CREATE TABLE IF NOT EXISTS whitelist ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, identifier VARCHAR(64) NOT NULL, note VARCHAR(120) NULL, added_by VARCHAR(64) NULL, added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY u_identifier (identifier) );
Controllo lato server (oxmysql)
-- Requires oxmysql. Add to fxmanifest: '@oxmysql/lib/MySQL.lua'
AddEventHandler('playerConnecting', function(name, setKickReason, deferrals)
local src = source
deferrals.defer()
deferrals.update('Verifying whitelist...')
local ids = {}
for _, id in ipairs(GetPlayerIdentifiers(src)) do table.insert(ids, id) end
-- Single scalar: any identifier approved?
local rowCount = MySQL.scalar.await(
'SELECT COUNT(*) FROM whitelist WHERE identifier IN (?)',
{ ids }
)
if rowCount and rowCount > 0 then
return deferrals.done()
else
return deferrals.done('Access denied. Apply at discord.gg/yourinvite')
end
end)
Comandi di amministrazione QoL (esempio)
RegisterCommand('wladd', function(src, args)
if src ~= 0 then return end -- console only for simplicity
local identifier = args[1]
if not identifier or not identifier:find(':') then
print('Usage: wladd identifierType:identifierValue')
return
end
local ok = MySQL.prepare.await('INSERT IGNORE INTO whitelist (identifier,note,added_by) VALUES (?, ?, ?)', {
identifier, 'manual add', 'console'
})
print(ok and ('Whitelisted: %s'):format(identifier) or 'Failed to add')
end, true)
RegisterCommand('wlrm', function(src, args)
if src ~= 0 then return end
local identifier = args[1]
local ok = MySQL.prepare.await('DELETE FROM whitelist WHERE identifier = ?', { identifier })
print(ok and ('Removed: %s'):format(identifier) or 'Failed to remove')
end, true)
Per mysql-asincrono, sostituire
MySQL.scalar.awaitconMySQL.Async.fetchScalare lo stile del parametro con@param/?Preferire oxmysql per le prestazioni e attendere il supporto.
Prestazione
- Mantieni un Indice UNICO SU
identifier(vedi schema). - Facoltativamente riscaldare una cache di memoria all'avvio e in caso di modifica; colpisce il DB solo in caso di cache miss.
- Limita la frequenza dei tentativi di connessione ripetuti e falliti da parte di
license/IP.
Regole multi-identificatore
Alcuni server richiedono più ID (ad esempio, sia Steam che Discord) per i livelli dello staff. Esempio di schema:
local function hasType(ids, typ)
for id, _ in pairs(ids) do if id:sub(1, #typ+1) == (typ..':') then return true end end
return false
end
-- Require license, and if staff, also discord
if not hasType(ids, 'license') then
return deferrals.done('Start the game normally (license missing).')
end
if staffModeEnabled and not hasType(ids, 'discord') then
return deferrals.done('Join our Discord and link your account to enter.')
end
Utilizzo di Discord come Whitelist (nessun codice personalizzato)
Se la tua community funziona su Discord, usa txAdmin Membro di Discord O Ruolo di Discord modalità:
- Collega txAdmin alla tua gilda Discord.
- Scegliere Membro di Discord per consentire a qualsiasi membro della gilda, o Ruolo di Discord per assegnare un ruolo specifico (ad esempio,
@Whitelisted). - Mantenere Licenza approvata come seconda porta se si desiderano entrambe le condizioni.
Buone pratiche: mantenere un #whitelist-requests Canale + modulo leggero. Automatizza l'assegnazione dei ruoli dopo l'approvazione tramite un bot o un flusso di moderazione.
FAX: un sistema di whitelist Discord per FiveM
Idee di integrazione
- Bot Discord: approvazione automatica quando un utente completa una domanda, aumenta la popolarità o si abbona.
- Pannello web: il personale aggiunge/rimuove gli identificatori, con traccia di controllo.
- Livelli a pagamento: concessione
discord roletramite il tuo negozio (Tebex/Patreon) e lascia che la modalità ruolo txAdmin imponga l'accesso.
Risoluzione dei problemi e insidie
- Il lettore non viene visualizzato nelle richieste txAdmin: Assicurati che la whitelist sia abilitata nel profilo corretto; controlla che il giocatore abbia effettivamente raggiunto la fase di rinvio (guarda la console live di txAdmin).
- ID Steam mancante: Steam deve essere in esecuzione; non impostare la tua whitelist esclusivamente su
steam:Preferirelicense:. - ID Discord mancante: L'utente deve avere Discord in esecuzione e il tuo server deve essere configurato per la lettura
discord:; verifica l'integrazione con Discord. licensecontrolicense2: Alcuni framework registrano due campi di licenza; assicurati che le tue query di migrazione/DB prendano in considerazione entrambi quando sposti i dati.- Timeout di rinvio: Chiama sempre
deferrals.update(...)mentre attendi DB; rispondi entro circa 10–15 secondi. - Formato identificativo non corrispondente: Assicurati di incollare
type:valueesattamente (carattere minuscolo, separatore due punti). - picchi di traffico elevati: Cache whitelist in memoria, preriscaldamento all'avvio e chiamate DB anti-rimbalzo.
FAQ SEO (contenuto pronto per Schema)
Qual è il miglior identificatore per la whitelist FiveM?
La rockstar license: è il più universale e affidabile; usalo come chiave primaria.
Posso inserire Discord nella whitelist senza dover scrivere codice?
Sì. txAdmin supporta Membro di Discord E Ruolo di Discord modalità nella whitelist una volta collegato Discord.
Ho bisogno di Steam per la whitelist?
No. Molti giocatori non usano Steam; evita di farlo steam: obbligatorio per l'accesso di base.
Posso combinare più controlli (ad esempio, licenza + ruolo Discord)?
Sì. Utilizza la modalità ruolo txAdmin E conserva un controllo della licenza nel tuo script personalizzato o nel flusso di ammissione.
Come posso pre-approvare i giocatori?
txAdmin → Whitelist → Aggiungi approvazione, impasto identifierType:identifier (per esempio, license:...).
Copia e incolla i messaggi di rifiuto (usa il tuo marchio)
- Basato su coda:
You’re not whitelisted yet. Apply in #whitelist-requests → discord.gg/yourinvite - Ruolo-gated:
Your Discord account doesn’t have @Whitelisted. Join discord.gg/yourinvite and request access. - Manutenzione:
Server is in Admin‑only mode for maintenance. Please try again later.
Conclusione
Una whitelist FiveM convalida gli identificativi dei giocatori durante la fase di rinvio della connessione e blocca gli utenti non approvati prima del caricamento delle risorse. Per la maggior parte dei server, abilitare Licenza approvata in txAdmin, facoltativamente strato Ruolo di Discord per l'accesso alla comunità e utilizzare un Supportato da DB elenco con memorizzazione nella cache per la scalabilità.
Appendice: Esempio minimo originale (per riferimento)
-- server.lua
local whitelist = {
["steam:110000132456789"] = true,
["license:abc123def456789"] = true,
["discord:123456789012345678"] = true
}
AddEventHandler("playerConnecting", function(name, setKickReason, deferrals)
local player = source
local identifiers = GetPlayerIdentifiers(player)
local whitelisted = false
deferrals.defer()
for _, id in pairs(identifiers) do
if whitelist[id] then
whitelisted = true
break
end
end
if not whitelisted then
deferrals.done("Not whitelisted. Apply at: your-discord.gg/invite")
else
deferrals.done()
end
end)