Plugins installeren op een Rust-server (Oxide en Carbon)

Een plugin voor Rust is één bestand met de extensie .cs. Je uploadt het naar de juiste map en het framework laadt het vanzelf, zonder de server te herstarten. We laten zien waar je plugins vindt, hoe je ze installeert, instelt, vertaalt, bijwerkt en verwijdert, en wat je doet als ze niet laden.

Hoe plugins werken#

• Een plugin is broncode in C#. Het framework houdt de map met plugins in de gaten en compileert en laadt een nieuw of gewijzigd bestand vanzelf. Je hoeft de server daarvoor niet te herstarten.
• Bij de eerste keer laden maakt een plugin meestal een configuratiebestand (JSON) aan met dezelfde naam als de plugin, en eventueel data (homes van spelers, cooldowns…) en taalbestanden.
• Oxide en Carbon gebruiken dezelfde plugins. Alleen de namen van de mappen en het voorvoegsel van de commando's verschillen.

Waar je plugins vindt#

• umod.org (opent in een nieuw venster) – de website van het project Oxide met duizenden gratis plugins (ze werken ook op Carbon). Filter in de lijst op het spel Rust.
• Betaalde marktplaatsen en websites van makers – daar worden uitgebreidere plugins verkocht (events, economieën, kaarten). Koop alleen bij de oorspronkelijke verkoper.

Controleer bij elke plugin vóór de installatie:

• De datum van de laatste update. Een plugin die na een grote update van Rust niet is bijgewerkt, compileert mogelijk niet.
• De beschrijving van de rechten en commando's op de pagina van de plugin. Zonder die informatie kun je hem niet instellen.
• Afhankelijkheden. Sommige plugins hebben een andere plugin nodig (bijvoorbeeld ImageLibrary voor afbeeldingen in menu's).

Een plugin installeren#

Controleer of de plugin draait door de plugins in de console op te vragen:

Mappenstructuur#

Het verschil tussen configuratie en data: de configuratie pas jij aan (hoe de plugin zich moet gedragen), de data beheert de plugin zelf (wat hij over spelers onthoudt). Pas data niet handmatig aan, tenzij je precies weet wat je doet.

De configuratie van een plugin aanpassen#

De configuratie heet naar de plugin: de plugin Kits.cs heeft zijn instellingen in oxide/config/Kits.json (in Carbon carbon/configs/Kits.json). Is het bestand na het laden van de plugin niet aangemaakt, dan valt er aan de plugin niets in te stellen, of hij is niet geladen (kijk in de logs).

Een veilige werkwijze waarbij de plugin jouw wijzigingen niet overschrijft:

Waarom eerst ontladen: sommige plugins slaan bij het ontladen hun huidige configuratie op. Als je het bestand aanpast terwijl de plugin draait en daarna alleen reload uitvoert, kan de plugin jouw wijzigingen overschrijven met de oorspronkelijke waarden. Bij plugins die dat niet doen, is het genoeg om het bestand op te slaan en oxide.reload Kits (c.reload Kits) uit te voeren.

Regels van JSON#

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

• Sleutels en teksten altijd tussen dubbele aanhalingstekens ("Enabled"). Enkele aanhalingstekens kent JSON niet.
• Na elk item een komma, behalve na het laatste in het betreffende blok. Een extra komma vóór } of ] is de meest voorkomende fout.
• true en false in kleine letters en zonder aanhalingstekens. "true" tussen aanhalingstekens is tekst, niet “aan”.
• Getallen zonder aanhalingstekens: 600, decimale getallen met een punt: 1.5.
• Een lijst staat tussen vierkante haken [ ], een groep instellingen tussen accolades { }.
• JSON ondersteunt geen commentaar. Verander de namen van de sleutels niet, alleen de waarden achter de dubbele punt.

Controleer het bestand vóór het uploaden met een JSON-validator (dat kan bijvoorbeeld de editor Visual Studio Code, die de fout onderstreept). Heb je de configuratie helemaal verprutst, verwijder haar dan en laad de plugin opnieuw – hij maakt een standaardbestand aan.

Plugins naar andere talen vertalen#

De teksten die een plugin naar spelers stuurt, staan in de bestanden oxide/lang/<taal>/<Plugin>.json (Carbon: carbon/lang/…). De plugin kiest de taal op basis van de taal die de speler in het spel heeft ingesteld. Bestaat er voor die taal geen bestand, dan gebruikt hij de taal van de server en ten slotte Engels.

Je hebt twee mogelijkheden:

• Alle spelers in jouw taal: vertaal direct het Engelse bestand oxide/lang/en/<Plugin>.json. Iedereen die geen eigen taalversie heeft, ziet het.
• Jouw taal alleen voor spelers met het spel in die taal: maak een map met de taalcode aan (bijvoorbeeld oxide/lang/nl voor Nederlands), kopieer het Engelse bestand erheen en vertaal het. Zien spelers met het spel in die taal de teksten nog steeds in het Engels, gebruik dan de eerste mogelijkheid.

Vertaal alleen de teksten achter de dubbele punt. Laat plaatshouders zoals {0} of {player} ongewijzigd, de plugin vult daar de waarden in. Kleurtags zoals <color=#ff5555>…</color> kun je laten staan of aanpassen. Bij een update van de plugin vult het framework het taalbestand alleen aan met nieuwe teksten, je vertalingen blijven behouden.

De standaardtaal van de server stel je in met het commando oxide.lang in de console van de server, bijvoorbeeld oxide.lang nl voor Nederlands (in Carbon c.lang nl).

Afhankelijkheden en extensies#

Een afhankelijkheid van een andere plugin herken je aan de beschrijving van de plugin of aan een fout in de console (zie Als iets niet werkt). De oplossing: installeer ook de vereiste plugin, op dezelfde manier in de map met plugins. Een typisch voorbeeld is ImageLibrary, dat voor andere plugins afbeeldingen voor menu's downloadt en opslaat.

Een extensie (extension) is een .dll-bestand, geen .cs. Ze worden bijvoorbeeld gebruikt door eigen kaarten uit de editor RustEdit of voor een koppeling met Discord. Extensies worden alleen bij het starten van de server geladen:

• Oxide: upload de .dll naar RustDedicated_Data/Managed en herstart de server.
• Carbon: upload de .dll naar carbon/extensions en herstart de server.

Let op bij Oxide: een update van het spel overschrijft bestanden in de map RustDedicated_Data/Managed. Eigen extensies Oxide.Ext.*.dll blijven meestal staan, maar als je de map Managed verwijdert (bijvoorbeeld bij het repareren van een beschadigde installatie), zijn ze weg. Bewaar er daarom ook buiten de server een back-up van.

Commando's voor het beheer van plugins#

Vervang Kits door de naam van de plugin, dus de bestandsnaam zonder .cs. Voer de commando's in de console van de server in, via RCON, of als admin in de console F1 in het spel.

Een plugin bijwerken#

1. Lees op de pagina van de plugin de lijst met wijzigingen. Hoofdversies (bijvoorbeeld van 3.x naar 4.x) kunnen de configuratie veranderen.
2. Maak een back-up van de configuratie en de data van de plugin.
3. Upload het nieuwe .cs-bestand over het oude heen (dezelfde naam).
4. Het framework merkt de wijziging op en laadt de plugin vanzelf opnieuw. In de console zie je dat de plugin is ontladen en opnieuw is geladen.

De configuratie en de data blijven behouden. Nieuwe instellingen die in de nieuwe versie zijn bijgekomen, vullen de meeste plugins zelf aan in de configuratie.

Een plugin verwijderen#

1. Ontlaad de plugin: oxide.unload Kits (Carbon: c.unload Kits).
2. Verwijder het bestand Kits.cs uit de map met plugins.
3. Wil je de plugin ook in de toekomst niet meer gebruiken, verwijder dan ook zijn configuratie, data en taalbestanden (bestanden en mappen met de naam van de plugin in config/configs, data en lang).

De rechten van een verwijderde plugin blijven aan de groepen toegekend. Dat kan geen kwaad, maar het maakt het er niet overzichtelijker op. In Carbon ruimt het commando c.cleanup orphans ze op.

Veiligheid#

• Een plugin kan op de server alles: bestanden lezen en verwijderen, consolecommando's uitvoeren, gegevens naar het internet sturen. Installeer alleen plugins die je vertrouwt.
• Installeer nooit “gelekte” (illegaal verspreide) betaalde plugins. Ze zijn vaak zo aangepast dat een aanvaller adminrechten of toegang tot de server krijgt.
• Een plugin is leesbare broncode. Vind je er verhulde code in of downloads van onbekende adressen, gebruik hem dan niet.
• Vul het RCON-wachtwoord nooit in op websites en in tools van anderen die je niet kent.

Als iets niet werkt#

In de console staat Error while compiling Kits:#

De plugin kon niet worden gecompileerd. Na de dubbele punt (Oxide vermeldt de naam van de plugin zonder .cs) volgt een lijst met fouten met het regelnummer (bijvoorbeeld error CS0246). Dezelfde reden toont oxide.plugins bij een plugin die niet is geladen. In Carbon begint een vergelijkbare fout met Failed compiling 'Kits.cs':. De meest voorkomende oorzaken:

• De plugin is verouderd ten opzichte van de huidige versie van Rust of het framework. Download de nieuwste versie van de plugin, of wacht tot de maker die na de update van Rust uitbrengt.
• Het bestand is beschadigd gedownload (bijvoorbeeld een webpagina in plaats van code). Open het in een editor: het moet C#-code bevatten (regels met using … en namespace Oxide.Plugins), geen HTML. Download het opnieuw.

In de console staat … plugin requires missing dependency: …#

De plugin heeft een andere plugin nodig die niet op de server staat. De naam van de ontbrekende plugin staat aan het einde van de melding. Installeer die, de plugin wordt daarna vanzelf geladen (of laad hem met het commando oxide.load). In Carbon luidt de melding Couldn't find required plugin '…' for '…', retrying...

De plugin is helemaal niet verschenen, de console blijft stil#

• Het bestand staat in een submap (bijvoorbeeld oxide/plugins/Kits/Kits.cs). Het moet direct in de map plugins staan.
• Het bestand heeft een andere extensie: .cs.txt, .zip of .dll. Pak een archief eerst uit op je computer en upload alleen de .cs.
• Het framework draait niet. Controleer oxide.version (Carbon: c.version), zie Oxide en Carbon.

Wijzigingen in de configuratie zijn na een herstart teruggedraaid#

De plugin heeft het bestand overschreven. Of je hebt het aangepast terwijl de plugin draaide en de plugin heeft bij het ontladen zijn eigen versie opgeslagen, of de JSON was ongeldig en de plugin heeft de standaardinstellingen aangemaakt. Volg de veilige werkwijze (ontladen, aanpassen, laden) en controleer het bestand vooraf met een validator.

De plugin meldt een fout bij het lezen van de configuratie#

De fout bevat meestal JsonReaderException of JsonSerializationException en een aanduiding als line 12, position 5. Op de genoemde regel staat een fout in de JSON, meestal een ontbrekende of overbodige komma of een aanhalingsteken. Herstel de fout, of zet de back-up terug.

Een commando van de plugin werkt niet voor spelers#

De spelers hebben het recht niet. Bij de meeste plugins moet je rechten toekennen aan de groep default of aan een specifieke groep. Zie Rechten op een Rust-server.

Meer bronnen#

• Oxide: plugins installeren (opent in een nieuw venster)
• Oxide: plugins configureren (opent in een nieuw venster)
• Oxide: vertalingen (localization) (opent in een nieuw venster)
• Carbon: documentatie voor servereigenaren (opent in een nieuw venster)
• Plugins voor Rust op umod.org (opent in een nieuw venster)