Instalacja pluginów na serwerze Rust (Oxide i Carbon)

Plugin Rust to jeden plik z rozszerzeniem .cs. Przesyłasz go do właściwego folderu, a framework sam go ładuje, bez restartu serwera. Ten poradnik pokazuje, gdzie znaleźć pluginy, jak je instalować, konfigurować, tłumaczyć, aktualizować i usuwać oraz co robić, gdy się nie ładują.

Jak działają pluginy#

• Plugin to kod źródłowy C#. Framework obserwuje folder pluginów i sam kompiluje oraz ładuje każdy nowy lub zmieniony plik. Nie trzeba do tego restartować serwera.
• Przy pierwszym wczytaniu plugin zwykle tworzy plik konfiguracyjny (JSON) o tej samej nazwie co plugin, a ewentualnie dane (domy graczy, cooldowny…) i pliki językowe.
• Oxide i Carbon używają tych samych pluginów. Różnią się tylko nazwy folderów i prefiks poleceń.

Gdzie znaleźć pluginy#

• umod.org (otwiera się w nowym oknie) – strona projektu Oxide z tysiącami bezpłatnych pluginów (działają też na Carbonie). Przefiltruj listę według gry Rust.
• Płatne sklepy i strony autorów – sprzedawane są tam większe pluginy (eventy, ekonomie, mapy). Kupuj tylko od oryginalnego sprzedawcy.

Przed instalacją każdego pluginu sprawdź:

• Datę ostatniej aktualizacji. Plugin niezaktualizowany po dużej aktualizacji Rusta może się nie skompilować.
• Opis uprawnień i poleceń na stronie pluginu. Bez nich go nie skonfigurujesz.
• Zależności. Niektóre pluginy potrzebują innego pluginu (na przykład ImageLibrary do obrazów w menu).

Instalacja pluginu#

Sprawdź, czy plugin działa, wypisując pluginy w konsoli:

Struktura folderów#

Różnica między konfiguracją a danymi: konfigurację edytujesz Ty (jak plugin ma się zachowywać), danymi plugin zarządza sam (co pamięta o graczach). Nie edytuj danych ręcznie, chyba że dokładnie wiesz, co robisz.

Edycja konfiguracji pluginu#

Konfiguracja nosi nazwę pluginu: plugin Kits.cs trzyma ustawienia w oxide/config/Kits.json (w Carbonie carbon/configs/Kits.json). Jeśli plik nie pojawił się po załadowaniu pluginu, plugin albo nie ma nic do konfigurowania, albo się nie załadował (sprawdź logi).

Bezpieczna procedura, która zapobiega nadpisaniu Twoich zmian przez plugin:

Dlaczego najpierw wyładować: niektóre pluginy zapisują bieżącą konfigurację przy wyładowaniu. Gdyby plik edytowano przy działającym pluginie i potem uruchomiono tylko reload, plugin mógłby nadpisać Twoje zmiany starymi wartościami. Przy pluginach, które tego nie robią, możesz po prostu zapisać plik i uruchomić oxide.reload Kits (c.reload Kits).

Zasady JSON#

{
  "Enabled": true,
  "Cooldown (seconds)": 600,
  "Welcome message": "Witaj na serwerze!",
  "Allowed items": [
    "rock",
    "torch"
  ],
  "Colors": {
    "Admin": "#ff5555",
    "Player": "#55aaff"
  }
}

• Klucze i tekst zawsze w podwójnych cudzysłowach ("Enabled"). JSON nie zna pojedynczych cudzysłowów.
• Przecinek po każdym elemencie poza ostatnim w danym bloku. Zbędny przecinek przed } lub ] to najczęstszy błąd.
• true i false małymi literami i bez cudzysłowów. "true" w cudzysłowie to tekst, nie „włączone”.
• Liczby bez cudzysłowów: 600; ułamki z kropką: 1.5.
• Lista w nawiasach kwadratowych [ ], grupa ustawień w nawiasach klamrowych { }.
• JSON nie obsługuje komentarzy. Nie zmieniaj nazw kluczy, tylko wartości po dwukropku.

Przed przesłaniem sprawdź plik walidatorem JSON (edytor taki jak Visual Studio Code robi to sam i podkreśla błąd). Jeśli zepsujesz konfigurację całkowicie, usuń ją i załaduj plugin ponownie – utworzy domyślny plik.

Tłumaczenie pluginów na inne języki#

Teksty, które plugin wysyła graczom, są w plikach oxide/lang/<język>/<Plugin>.json (Carbon: carbon/lang/…). Plugin wybiera język według języka ustawionego przez gracza w grze. Jeśli nie ma pliku dla tego języka, używa języka serwera, a na końcu angielskiego.

Masz dwie możliwości:

• Wszyscy gracze w Twoim języku: przetłumacz bezpośrednio angielski plik oxide/lang/en/<Plugin>.json. Zobaczy go każdy, kto nie ma własnej wersji językowej.
• Twój język tylko dla graczy, których gra go używa: utwórz folder nazwany kodem języka (na przykład oxide/lang/pl dla polskiego), skopiuj do niego angielski plik i przetłumacz go. Jeśli gracze z grą ustawioną na ten język nadal widzą angielskie teksty, użyj pierwszej opcji.

Tłumacz tylko teksty po dwukropku. Symbole zastępcze takie jak {0} czy {player} zostaw bez zmian; plugin wstawia w nie wartości. Znaczniki kolorów typu <color=#ff5555>…</color> możesz zachować lub dostosować. Przy aktualizacji pluginu framework tylko dopisuje do pliku językowego nowe teksty, więc Twoje tłumaczenia zostają.

Domyślny język serwera ustawisz poleceniem oxide.lang w konsoli serwera, na przykład oxide.lang pl dla polskiego (w Carbonie c.lang pl).

Zależności i rozszerzenia#

Zależność od innego pluginu widać w opisie pluginu albo jako błąd w konsoli (zobacz Rozwiązywanie problemów). Naprawa: zainstaluj także wymagany plugin, tak samo, do folderu pluginów. Typowy przykład to ImageLibrary, który pobiera i przechowuje obrazy menu dla innych pluginów.

Rozszerzenie to plik .dll, nie .cs. Używają ich na przykład własne mapy z edytora RustEdit albo integracja z Discordem. Rozszerzenia są ładowane tylko przy starcie serwera:

• Oxide: prześlij .dll do RustDedicated_Data/Managed i zrestartuj serwer.
• Carbon: prześlij .dll do carbon/extensions i zrestartuj serwer.

Zastrzeżenie dla Oxide: aktualizacja gry nadpisuje pliki w folderze RustDedicated_Data/Managed. Twoje własne rozszerzenia Oxide.Ext.*.dll zwykle przetrwają, ale jeśli kiedykolwiek usuniesz folder Managed (na przykład przy naprawie zepsutej instalacji), znikną. Trzymaj ich kopie także poza serwerem.

Polecenia do zarządzania pluginami#

Zamiast Kits wstaw nazwę pluginu, czyli nazwę pliku bez .cs. Polecenia wpisuj w konsoli serwera, przez RCON albo jako admin w konsoli F1 w grze.

Aktualizacja pluginu#

1. Przeczytaj changelog na stronie pluginu. Duże wersje (na przykład 3.x na 4.x) mogą zmieniać konfigurację.
2. Zarchiwizuj konfigurację i dane pluginu.
3. Prześlij nowy plik .cs na miejsce starego (ta sama nazwa).
4. Framework wykrywa zmianę i sam przeładowuje plugin. Konsola pokazuje wyładowanie i ponowne załadowanie pluginu.

Konfiguracja i dane zostają. Większość pluginów sama dopisuje do konfiguracji nowe ustawienia wprowadzone w nowej wersji.

Usuwanie pluginu#

1. Wyładuj plugin: oxide.unload Kits (Carbon: c.unload Kits).
2. Usuń plik Kits.cs z folderu pluginów.
3. Jeśli nie chcesz pluginu także w przyszłości, usuń też jego konfigurację, dane i pliki językowe (pliki i foldery nazwane od pluginu w config/configs, data i lang).

Uprawnienia usuniętego pluginu pozostają przypisane do grup. Nie szkodzi to, ale nie pomaga w porządku. W Carbonie sprząta je polecenie c.cleanup orphans.

Bezpieczeństwo#

• Plugin może na serwerze wszystko: czytać i usuwać pliki, wykonywać polecenia konsoli, wysyłać dane do internetu. Instaluj tylko pluginy, którym ufasz.
• Nigdy nie instaluj „leaknietych” (nielegalnie rozpowszechnianych) płatnych pluginów. Często są zmodyfikowane tak, aby dać atakującemu uprawnienia admina lub dostęp do serwera.
• Plugin to czytelny kod źródłowy. Jeśli znajdziesz w nim zaciemniony kod albo pobieranie z nieznanych adresów, nie używaj go.
• Nigdy nie wklejaj hasła RCON na strony i do narzędzi, których nie znasz.

Rozwiązywanie problemów#

W konsoli jest Error while compiling Kits:#

Pluginu nie dało się skompilować. Po dwukropku (Oxide podaje nazwę pluginu bez .cs) następuje lista błędów z numerami linii (na przykład error CS0246). oxide.plugins pokazuje ten sam powód przy pluginie, który się nie załadował. W Carbonie podobny błąd zaczyna się od Failed compiling 'Kits.cs':. Najczęstsze przyczyny:

• Plugin jest przestarzały dla bieżącej wersji Rusta lub frameworka. Pobierz najnowszą wersję pluginu albo poczekaj, aż autor wyda ją po aktualizacji Rusta.
• Plik pobrano uszkodzony (na przykład stronę WWW zamiast kodu). Otwórz go w edytorze: musi zawierać kod C# (linie typu using … i namespace Oxide.Plugins), nie HTML. Pobierz go ponownie.

W konsoli jest … plugin requires missing dependency: …#

Plugin potrzebuje innego pluginu, którego nie ma na serwerze. Nazwa brakującego pluginu jest na końcu komunikatu. Zainstaluj go, a plugin załaduje się sam (albo załaduj go przez oxide.load). W Carbonie komunikat brzmi Couldn't find required plugin '…' for '…', retrying...

Plugin w ogóle się nie pojawił, konsola milczy#

• Plik jest w podfolderze (na przykład oxide/plugins/Kits/Kits.cs). Musi być bezpośrednio w folderze plugins.
• Plik ma inne rozszerzenie: .cs.txt, .zip lub .dll. Archiwa najpierw rozpakuj na komputerze i prześlij tylko .cs.
• Framework nie działa. Sprawdź oxide.version (Carbon: c.version), zobacz Oxide i Carbon.

Zmiany w konfiguracji cofnęły się po restarcie#

Plugin nadpisał plik. Albo edytowano go przy działającym pluginie i plugin zapisał własną wersję przy wyładowaniu, albo JSON był nieprawidłowy i plugin utworzył ustawienia domyślne. Postępuj według bezpiecznej procedury (wyładuj, edytuj, załaduj) i wcześniej sprawdź plik walidatorem.

Plugin zgłasza błąd przy czytaniu konfiguracji#

Błąd zwykle zawiera JsonReaderException lub JsonSerializationException i pozycję typu line 12, position 5. W tej linii jest błąd JSON, zwykle brakujący lub zbędny przecinek albo cudzysłów. Popraw go albo przywróć kopię.

Gracze nie mogą użyć polecenia pluginu#

Gracze nie mają uprawnienia. Większość pluginów wymaga nadania uprawnień grupie default lub konkretnej grupie. Zobacz Uprawnienia na serwerze Rust.

Dalsza lektura#

• Oxide: instalacja pluginów (otwiera się w nowym oknie)
• Oxide: konfiguracja pluginów (otwiera się w nowym oknie)
• Oxide: lokalizacja (otwiera się w nowym oknie)
• Carbon: dokumentacja dla właścicieli serwerów (otwiera się w nowym oknie)
• Pluginy Rust na umod.org (otwiera się w nowym oknie)