FiveM: whitelist přes Discord a oprávnění podle rolí

Discord na FiveM serveru plní dvě oddělené úlohy a hned je to jednodušší, když je přestaneš brát jako jednu. Whitelist rozhoduje, kdo se vůbec smí připojit: txAdmin to umí sám, podle členství na Discord serveru nebo podle role, bez jakéhokoli doplňku. Oprávnění určují, co smí připojený hráč dělat: jde o převod rolí z Discordu na ACE skupiny pomocí add_principal identifier.discord:<id> group.<name> v okamžiku připojení, buď hotovým resource, nebo čtyřiceti řádky vlastního kódu. Obojí potřebuje Discord bota ve tvé guildě a obojí závisí na Discord identifikátoru hráče, který existuje jen tehdy, když při spuštění FiveM běží desktopová aplikace Discordu. Tento návod nastaví bota, whitelist v txAdminu a mapování rolí na ACE a projde i chyby, na které narazíš během prvního týdne.

Jak do sebe díly zapadají#

Když se hráč připojuje, FXServer shromáždí jeho identifikátory - license, discord, fivem, xbl, live, IP a steam, pokud máš nastavený Steam Web API klíč. Identifikátor discord je ID uživatele na Discordu a je k dispozici jen tehdy, když při startu FiveM běžel a byl přihlášený desktopový klient Discordu. Discord v záložce prohlížeče se nepočítá.

Krok whitelistu se přes tvého bota zeptá Discordu, jestli je daný uživatel v tvé guildě a jaké má role, a připojení přijme nebo odmítne. Krok oprávnění vezme stejné role a přidá Discord identifikátor hráče do ACE skupin, takže ho vidí IsPlayerAceAllowed i příkazy omezené přes ACE. První krok řeší txAdmin. Druhý je resource, protože vlastní seznam adminů v txAdminu řídí jeho webový panel a herní menu, ne ACE.

Vytvoření Discord bota#

Oba kroky potřebují účet bota na tvém Discord serveru. Nemusí běžet jako samostatný program - txAdmin i resource pro oprávnění používají jeho token k odesílání požadavků.

1. Otevři Discord Developer Portal, vytvoř New Application a přidej k ní Bota.
2. Zkopíruj token bota. Ber ho jako heslo: kdo ho má, ovládá bota a může číst seznam tvých členů.
3. Na stránce Bot zapni Server Members Intent. Vyhledávání členů a rolí na něm závisí a jeho zapomenutí je nejčastější důvod, proč whitelist odmítá úplně všechny.
4. V části OAuth2 vygeneruj pozvánku s oprávněním bot a pozvi bota do své guildy. Ke čtení členů a rolí nepotřebuje žádná zvláštní práva.
5. V Discordu zapni Developer Mode (User Settings, Advanced). Klikni pravým tlačítkem na svůj server a zvol Copy Server ID, pak klikni pravým na každou roli, která tě zajímá, a zvol Copy Role ID.

Teď máš token, ID guildy a seznam ID rolí. Token ukládej jen na jedno místo. Pokud ho dáš do server.cfg, použij set, nikdy sets ani setr - sets zveřejní hodnotu v seznamu serverů, odkud ji někdo vyčte. O tom, jak ho udržet mimo screenshoty a repozitáře, píše Proměnné prostředí a tajné údaje.

Whitelist přes txAdmin#

txAdmin má vestavěný whitelist i vestavěnou integraci Discord bota, takže na samotnou bránu žádný resource nepotřebuješ.

1. V txAdminu otevři Settings a kartu Discord. Zapni bota, vlož token a ID guildy a ulož. txAdmin se připojí a ohlásí, jestli guildu dokázal vidět.
2. Otevři nastavení whitelistu (v současných verzích Settings, Player Manager) a vyber režim.

Přesné názvy se mezi verzemi txAdminu trochu liší, ale těchto pět chování je stabilních.

Discord server roles je to, co chce většina roleplay serverů: zájemci vstoupí na Discord, projdou přihláškou, dostanou roli „Whitelisted“ a od té chvíle se mohou připojit. Odebráním role se přístup odebere při jejich dalším připojení. Vkládej ID rolí, ne názvy; názvy se mohou opakovat a měnit, ID ne.

Approved license se hodí pro malý soukromý server bez Discordu. Odmítnutému hráči se zobrazí krátké ID žádosti; admin ji schválí na stránce whitelistu v txAdminu nebo příkazem bota na Discordu a hráč se může připojit.

Text zamítnutí se dá nastavit. Napiš do něj přesně, co mají hráči udělat - „Vstup na discord.gg/yourserver a dokonči přihlášku“ - a co zkontrolovat, když si myslí, že na whitelistu jsou: jestli běží aplikace Discord a jestli je přihlášený správný účet. Tahle jedna věta ušetří desítky tiketů na podporu.

Role z Discordu na ACE oprávnění#

Whitelist lidi pustí dovnitř. Abys roli z Discordu dal pravomoci ve hře - admin příkazy, menu pro tým, vozidlo pro donory - potřebuješ ACE principals. Mechanismus je stejný jako v článku FiveM server.cfg vysvětlen: skupiny drží aces a principal spojuje identifikátor hráče se skupinou.

add_ace group.admin command allowadd_ace group.admin command.quit denyadd_ace group.mod command.kick allowadd_principal group.admin group.mod

Statické řádky jako add_principal identifier.discord:216735154273419264 group.admin fungují, ale nesledují změny rolí na Discordu. Sleduje je resource, který při připojení hráče přidá principals podle jeho aktuálních rolí.

Nejznámější hotová možnost je dvojice resources od Badgera: Badger_Discord_API, která komunikuje s Discordem, a DiscordAcePerms, která při připojení mapuje ID rolí na skupiny. Jsou hojně používané a dobře zdokumentované; formát konfigurace hledej v jejich README, protože se mezi verzemi měnil.

Pokud chceš přesně vědět, co ti běží, je ta práce dost malá na to, abys ji napsal sám:

local GUILD = GetConvar("discord_guild_id", "")local TOKEN = GetConvar("discord_bot_token", "")-- Discord role ID -> ACE grouplocal ROLE_GROUPS = {    ["111111111111111111"] = "group.admin",    ["222222222222222222"] = "group.mod",    ["333333333333333333"] = "group.donor",}local function discordId(src)    local id = GetPlayerIdentifierByType(src, "discord")    return id and id:gsub("discord:", "")endAddEventHandler("playerConnecting", function(name, setKickReason, deferrals)    local src = source    deferrals.defer()    Wait(0)    deferrals.update("Checking your Discord roles...")    local id = discordId(src)    if not id then        deferrals.done("Open the Discord desktop app, then restart FiveM.")        return    end    local url = ("https://discord.com/api/v10/guilds/%s/members/%s"):format(GUILD, id)    PerformHttpRequest(url, function(status, body)        if status == 200 then            local member = json.decode(body)            for _, group in pairs(ROLE_GROUPS) do                ExecuteCommand(("remove_principal identifier.discord:%s %s"):format(id, group))            end            for _, role in ipairs(member.roles or {}) do                local group = ROLE_GROUPS[role]                if group then                    ExecuteCommand(("add_principal identifier.discord:%s %s"):format(id, group))                end            end        end        deferrals.done()    end, "GET", "", { Authorization = "Bot " .. TOKEN })end)

A v server.cfg:

set discord_guild_id "123456789012345678"set discord_bot_token "your-bot-token"add_ace resource.discord_perms command.add_principal allowadd_ace resource.discord_perms command.remove_principal allowensure discord_perms

Na dvou řádcích add_ace resource. záleží. Resource nemůže přes ExecuteCommand spustit add_principal, dokud k tomu příkazu nemá právo, a bez nich skript běží, nevypíše nic užitečného a nikdo svou skupinu nedostane.

Věci v kódu, kterým stojí za to porozumět, místo aby se jen kopírovaly:

• `deferrals.defer()` a potom `Wait(0)`. Odložení drží připojení, zatímco děláš asynchronní práci; to čekání je nutné před voláním update nebo done.
• Nejdřív odebrat, potom přidat. Principals se vážou na identifikátor a vydrží do restartu serveru, takže hráč, který na Discordu přišel o roli, si skupinu ponechá, dokud ji neodebereš. Smyčka proto nejdřív vyčistí všechny mapované skupiny.
• Nečlen se tady dovnitř dostane. Tento resource jen mapuje oprávnění. Odmítat nečleny je práce txAdminu; dělat to na dvou místech znamená dvě místa k ladění.
• `GetPlayerIdentifierByType` je dostupná v aktuálních buildech serveru. Na velmi starých projdi místo toho GetPlayerIdentifiers(src) ve smyčce.

Oprávnění frameworku jsou třetí systém#

ACE je oprávnění systém FiveM, ale frameworky si nad něj dávají vlastní a s ACE se propojují různě.

• QBCore používá ACE přímo. Jeho úrovně oprávnění jsou ACE skupiny jako qbcore.god, qbcore.admin a qbcore.mod, takže role z Discordu namapovaná na qbcore.admin funguje s admin kontrolami QBCore. Přesné názvy najdeš v config.lua své verze.
• ESX ukládá hodnotu group každého hráče do své databáze (user, admin a podobně) a kontroluje ji. Namapování role z Discordu na ACE skupinu skupinu v ESX nezmění; potřebuješ resource, který ji nastaví přes framework, nebo ji nastavíš ručně.
• Qbox jde cestou QBCore a spoléhá na ACE.

Než začneš mapovat role, rozhodni, do kterého ze tří systémů každé oprávnění patří, a zapiš si to. „Proč moderátor otevře admin menu, ale nemůže nikoho vyhodit?“ je skoro vždy případ, kdy jeden systém povoluje a jiný zakazuje. O straně frameworků píše Porovnání FiveM frameworků.

Admini txAdminu a Discord#

txAdmin vede vlastní admin účty s vlastními oprávněními - kdo může kickovat, banovat, restartovat, upravovat konfiguraci a používat herní menu. Tyto účty lze propojit s Discord ID a FiveM identifikátorem, aby je herní menu poznalo, ale admin status v txAdminu a ACE skupiny zůstávají oddělené. Starší moderátor obvykle potřebuje obojí: účet txAdminu s právy na správu hráčů a roli na Discordu, která se mapuje na group.mod pro příkazy ve hře.

Drž oba seznamy krátké. Každý, kdo smí banovat, smí i odbanovat; každý, kdo smí upravovat konfiguraci, si může přečíst heslo k tvé databázi. Stejná úvaha platí pro panel, kde Subusery a nejmenší oprávnění vysvětluje, proč existuje přístup jen ke konzoli a jen k souborům. Na RE:NODE lze subuserům dát přesně tohle - jen konzole, jen soubory, žádná fakturace - a přístup lze časově omezit, což se hodí pro vývojáře, kterého pouštíš dovnitř na týden.

Proces přihlášek kolem toho#

Technický whitelist je ta snadná půlka. Proces, který rozhoduje, kdo dostane roli, dělá whitelistovaný server hodný připojení a stojí za to ho navrhnout záměrně.

• Jedna role pro přístup, zvláštní role pro oprávnění. „Whitelisted“ lidi pustí dovnitř. „Police“, „EMS“ a „Staff“ dávají věci ve hře. Když je smícháš - role policie dává i přístup - pak odebrání někoho z policie znamená, že ho zároveň vyřadíš ze serveru.
• Kanál nebo formulář pro přihlášky. Většina serverů používá Discord form bota nebo webový formulář. Ptej se na to, o čem opravdu rozhoduješ: věk, časové pásmo, zkušenost s roleplayem, krátký koncept postavy. Dlouhé eseje odfiltrují dobré hráče stejně jako ty špatné.
• Kdo smí roli udělit. Správu rolí na Discordu omez na lidi, kteří přihlášky posuzují. Kdo může udělit „Whitelisted“, ovládá dveře tvého serveru, a kdo může udělit „Staff“, ovládá všechno za nimi.
• Odebrání přístupu. Roli odeber u banů, které mají přesáhnout ban ve hře, a u hráčů, kteří opustí tvůj Discord. U whitelistu podle rolí se odchodem z guildy přístup odebere sám při dalším připojení.
• Neaktivní hráči. Některé servery po měsících nečinnosti roli whitelistu odeberou, aby komunita zůstala aktuální. Řekni to hráčům předem.

Pravidla si zapiš a připni je v kanálu pro přihlášky. Pravidla serveru, moderace a tým se lidské stránce věnuje podrobněji, včetně odvolání.

Rate limity a spolehlivost#

Discord omezuje počet požadavků botů. Jeden dotaz na každého připojujícího se hráče je pro jakýkoli běžný server hluboko pod limity, i v době restartu, kdy se za dvě minuty znovu připojí šedesát lidí. Potíže dělá opakovaná kontrola rolí, zatímco jsou hráči online - při každém příkazu, každou minutu, při každé změně povolání. Role zjisti při připojení, na dobu relace je ulož do cache a obnov jen na požádání.

Rozhodni, co se stane, když Discord neodpoví. Kód výše pustí hráče dovnitř bez skupin, což je pro oprávnění bezpečné selhání. U whitelistu je to naopak: selhání dovnitř pustí při výpadku Discordu kohokoli, selhání zavřením nepustí nikoho. txAdmin selhává zavřením, což je pro whitelist správně, a proto je záloha Admin-only důležitá.

Řešení potíží#

Role whitelist odmítá všechny. Server Members Intent je vypnutý, bot není v guildě, nebo je špatné ID guildy. Stránka nastavení Discordu v txAdminu hlásí, jestli bot guildu vidí.

Jednoho hráče to odmítá, přestože roli má. Jeho aplikace Discord při startu FiveM nebežela, je přihlášený k jinému účtu na Discordu, nebo účet v guildě není ten, který je propojený v jeho klientu. Požádej ho, ať zavře FiveM, otevře Discord a spustí to znovu.

Role se mapují, ale příkazy se pořád odmítají. Resource nemá řádek add_ace resource.<name> command.add_principal allow, nebo skupina nemá pro daný příkaz udělené aces.

Odebraní členové týmu si drží svá práva. Principals vydrží do restartu. Odeber před přidáním, jak je uvedeno výše, nebo server restartuj.

Oprávnění fungují ve hře, ale ne v txAdminu. Jsou to různé systémy. Dej dotyčnému také účet v txAdminu.

FAQ#

Musí mít hráči Discord otevřený, aby se připojili k serveru s Discord whitelistem?

Ano. Discord identifikátor pochází z desktopové aplikace Discordu, která běží při startu FiveM. Bez ní není co kontrolovat a whitelist podle rolí připojení odmítne.

Můžu dělat whitelist bez instalace resource?

Ano. Whitelist txAdminu podporuje členství na Discord serveru i role na Discordu přímo, jakmile je nastavený jeho Discord bot. Resources jsou potřeba jen k převodu rolí na ACE oprávnění ve hře.

Proč používat ID rolí místo názvů rolí?

Názvy může změnit nebo zdvojit kdokoli s právem spravovat role, což by tiše změnilo, kdo se dostane dovnitř. ID jsou po celou dobu existence role pevná.

Dělá z někoho admin v txAdminu admina i ve hře?

Ne ve smyslu ACE. Admini txAdminu mohou používat jeho vlastní menu a panel, ale ACE skupiny a skupiny frameworku jsou samostatné a každá se musí udělit zvlášť.

Co když mi unikne token bota?

Ihned ho resetuj v Developer Portalu a aktualizuj všude, kde je uložený. Uniklý token umožní komukoli jednat jako bot a číst seznam členů tvé guildy.