Instalace pluginů na Rust server (Oxide i Carbon)

Plugin pro Rust je jeden soubor s příponou .cs. Nahrajete ho do správné složky a framework ho sám načte, bez restartu serveru. Ukážeme, kde pluginy hledat, jak je nainstalovat, nastavit, přeložit, aktualizovat a odebrat a co dělat, když se nenačtou.

Jak pluginy fungují#

• Plugin je zdrojový kód v C#. Framework hlídá složku s pluginy a nový nebo změněný soubor sám přeloží a načte. Server kvůli tomu nemusíte restartovat.
• Při prvním načtení si plugin obvykle vytvoří konfigurační soubor (JSON) se stejným názvem jako plugin, případně data (domovy hráčů, cooldowny…) a jazykové soubory.
• Oxide i Carbon používají stejné pluginy. Liší se jen názvy složek a předpona příkazů.

Kde pluginy najít#

• umod.org (otevře se v novém okně) – web projektu Oxide s tisíci bezplatných pluginů (fungují i na Carbonu). V seznamu filtrujte hru Rust.
• Placená tržiště a weby autorů – prodávají se tam rozsáhlejší pluginy (eventy, ekonomiky, mapy). Kupujte jen u původního prodejce.

U každého pluginu před instalací zkontrolujte:

• Datum poslední aktualizace. Plugin, který nebyl aktualizovaný po velké aktualizaci Rustu, se nemusí přeložit.
• Popis oprávnění a příkazů na stránce pluginu. Bez nich ho nenastavíte.
• Závislosti. Některé pluginy potřebují jiný plugin (například ImageLibrary pro obrázky v menu).

Instalace pluginu#

Ověřte, že plugin běží, výpisem pluginů v konzoli:

Struktura složek#

Rozdíl mezi konfigurací a daty: konfiguraci upravujete vy (jak se má plugin chovat), data si spravuje plugin sám (co si pamatuje o hráčích). Data ručně neupravujte, pokud přesně nevíte, co děláte.

Úprava konfigurace pluginu#

Konfigurace má název podle pluginu: plugin Kits.cs má nastavení v oxide/config/Kits.json (v Carbonu carbon/configs/Kits.json). Pokud soubor po načtení pluginu nevznikl, plugin buď nic nastavovat neumí, nebo se nenačetl (podívejte se do logů).

Bezpečný postup, při kterém plugin vaše změny nepřepíše:

Proč nejdřív uvolnit: některé pluginy při uvolnění ukládají svou aktuální konfiguraci. Kdybyste soubor upravili za běhu a pak dali jen reload, plugin by vaše změny mohl přepsat původními hodnotami. U pluginů, které tohle nedělají, stačí soubor uložit a dát oxide.reload Kits (c.reload Kits).

Pravidla JSON#

{
  "Zapnuto": true,
  "Cooldown (sekundy)": 600,
  "Uvitaci zprava": "Vitej na serveru!",
  "Povolene predmety": [
    "rock",
    "torch"
  ],
  "Barvy": {
    "Admin": "#ff5555",
    "Hrac": "#55aaff"
  }
}

• Klíče i texty vždy v dvojitých uvozovkách ("Zapnuto"). Jednoduché uvozovky JSON nezná.
• Za každou položkou čárka, kromě poslední v daném bloku. Čárka navíc před } nebo ] je nejčastější chyba.
• true a false malými písmeny a bez uvozovek. "true" v uvozovkách je text, ne zapnuto.
• Čísla bez uvozovek: 600, desetinná čísla s tečkou: 1.5.
• Seznam je v hranatých závorkách [ ], skupina nastavení ve složených { }.
• Komentáře JSON nepodporuje. Neměňte názvy klíčů, jen hodnoty za dvojtečkou.

Před nahráním si soubor zkontrolujte validátorem JSON (umí to například editor Visual Studio Code, který chybu podtrhne). Když konfiguraci úplně pokazíte, smažte ji a plugin znovu načtěte – vytvoří si výchozí soubor.

Čeština a jiné jazyky#

Texty, které plugin posílá hráčům, jsou v souborech oxide/lang/<jazyk>/<Plugin>.json (Carbon: carbon/lang/…). Plugin vybírá jazyk podle jazyka, který má hráč nastavený ve hře. Když soubor pro jeho jazyk neexistuje, použije jazyk serveru a nakonec angličtinu.

Máte dvě možnosti:

• Všichni hráči česky: přeložte rovnou anglický soubor oxide/lang/en/<Plugin>.json. Uvidí ho každý, kdo nemá vlastní jazykovou verzi.
• Čeština jen pro hráče s českou hrou: vytvořte složku oxide/lang/cs, zkopírujte do ní anglický soubor a přeložte ho. Pokud hráči s češtinou ve hře texty dál vidí anglicky, použijte první možnost.

Překládejte jen texty za dvojtečkou. Zástupné znaky jako {0} nebo {player} nechte beze změny, plugin za ně dosadí hodnoty. Barevné značky jako <color=#ff5555>…</color> můžete ponechat nebo upravit. Při aktualizaci pluginu framework do jazykového souboru jen doplní nové texty, vaše překlady zůstanou.

Výchozí jazyk serveru nastavíte příkazem oxide.lang cs zadaným v konzoli serveru (v Carbonu c.lang cs).

Závislosti a rozšíření#

Závislost na jiném pluginu poznáte z popisu pluginu nebo z chyby v konzoli (viz Když něco nefunguje). Řešení: nainstalujte i požadovaný plugin, stejným postupem do složky s pluginy. Typický příklad je ImageLibrary, který pro jiné pluginy stahuje a ukládá obrázky do menu.

Rozšíření (extension) je soubor .dll, ne .cs. Používají ho například vlastní mapy z editoru RustEdit nebo propojení s Discordem. Rozšíření se načítají jen při startu serveru:

• Oxide: nahrajte .dll do RustDedicated_Data/Managed a server restartujte.
• Carbon: nahrajte .dll do carbon/extensions a server restartujte.

U Oxide pozor: aktualizace hry přepisuje soubory ve složce RustDedicated_Data/Managed. Vlastní rozšíření Oxide.Ext.*.dll obvykle zůstanou, ale kdybyste složku Managed mazali (například při opravě poškozené instalace), zmizí. Mějte je proto zálohované i mimo server.

Příkazy pro správu pluginů#

Za Kits dosaďte název pluginu, tedy název souboru bez .cs. Příkazy zadávejte do konzole serveru, přes RCON, nebo jako admin do konzole F1 ve hře.

Aktualizace pluginu#

1. Přečtěte si na stránce pluginu seznam změn. Hlavní verze (například 3.x na 4.x) mohou změnit konfiguraci.
2. Zálohujte konfiguraci a data pluginu.
3. Nahrajte nový soubor .cs přes ten starý (stejný název).
4. Framework změnu pozná a plugin sám znovu načte. V konzoli uvidíte, že se plugin uvolnil a znovu načetl.

Konfigurace i data zůstávají. Nová nastavení, která přibyla v nové verzi, si většina pluginů do konfigurace doplní sama.

Odebrání pluginu#

1. Plugin uvolněte: oxide.unload Kits (Carbon: c.unload Kits).
2. Smažte soubor Kits.cs ze složky s pluginy.
3. Pokud plugin už nechcete ani v budoucnu, smažte i jeho konfiguraci, data a jazykové soubory (soubory a složky se jménem pluginu v config/configs, data a lang).

Oprávnění odebraného pluginu zůstávají přidělená skupinám. Nevadí to, ale přehledu to nepomáhá. V Carbonu je uklidí příkaz c.cleanup orphans.

Bezpečnost#

• Plugin může na serveru cokoli: číst a mazat soubory, spouštět příkazy konzole, posílat data na internet. Instalujte jen pluginy, kterým důvěřujete.
• Nikdy neinstalujte „leaknuté“ (nelegálně šířené) placené pluginy. Bývají upravené tak, aby útočníkovi daly admin práva nebo přístup k serveru.
• Plugin je čitelný zdrojový kód. Pokud v něm najdete zamaskovaný kód nebo stahování z neznámých adres, nepoužívejte ho.
• Heslo RCON nikdy nevkládejte do cizích webů a nástrojů, které neznáte.

Když něco nefunguje#

V konzoli je Error while compiling Kits:#

Plugin se nepodařilo přeložit. Za dvojtečkou (Oxide uvádí název pluginu bez .cs) následuje seznam chyb s číslem řádku (například error CS0246). Stejný důvod ukáže i oxide.plugins u pluginu, který se nenačetl. V Carbonu podobná chyba začíná Failed compiling 'Kits.cs':. Nejčastější příčiny:

• Plugin je zastaralý vůči aktuální verzi Rustu nebo frameworku. Stáhněte nejnovější verzi pluginu, případně počkejte, až ji autor po aktualizaci Rustu vydá.
• Soubor se stáhl poškozený (například místo kódu webová stránka). Otevřete ho v editoru: musí obsahovat kód C# (řádky using … a namespace Oxide.Plugins), ne HTML. Stáhněte ho znovu.

V konzoli je … plugin requires missing dependency: …#

Plugin potřebuje jiný plugin, který na serveru není. Název chybějícího pluginu je na konci hlášky. Nainstalujte ho, plugin se pak načte sám (případně ho načtěte příkazem oxide.load). V Carbonu hláška zní Couldn't find required plugin '…' for '…', retrying...

Plugin se vůbec neobjevil, konzole mlčí#

• Soubor je v podsložce (například oxide/plugins/Kits/Kits.cs). Musí být přímo ve složce plugins.
• Soubor má jinou příponu: .cs.txt, .zip nebo .dll. Archiv nejdřív rozbalte v počítači a nahrajte jen .cs.
• Framework neběží. Ověřte oxide.version (Carbon: c.version), viz Oxide a Carbon.

Změny v konfiguraci se po restartu vrátily#

Plugin soubor přepsal. Buď jste ho upravovali za běhu a plugin při uvolnění uložil svou verzi, nebo byl JSON neplatný a plugin vytvořil výchozí nastavení. Postupujte podle bezpečného postupu (uvolnit, upravit, načíst) a soubor předem zkontrolujte validátorem.

Plugin hlásí chybu při čtení konfigurace#

Chyba obvykle obsahuje JsonReaderException nebo JsonSerializationException a údaj line 12, position 5. Na uvedeném řádku je chyba v JSON, většinou chybějící nebo přebývající čárka či uvozovka. Opravte ji, nebo vraťte zálohu.

Příkaz pluginu hráčům nefunguje#

Hráči nemají oprávnění. Většina pluginů vyžaduje přidělit oprávnění skupině default nebo konkrétní skupině. Viz Oprávnění na Rust serveru.

Další zdroje#

• Oxide: instalace pluginů (otevře se v novém okně)
• Oxide: konfigurace pluginů (otevře se v novém okně)
• Oxide: překlady (localization) (otevře se v novém okně)
• Carbon: dokumentace pro majitele serverů (otevře se v novém okně)
• Pluginy pro Rust na umod.org (otevře se v novém okně)