Plugins Rust : les bases d'Oxide et Carbon

Réponse rapide : installez Oxide ou Carbon sur le serveur, puis déposez le fichier .cs d’un plugin dans oxide/plugins/ ou carbon/plugins/. Il se charge tout seul, sans redémarrage, et son fichier de réglages apparaît dans le dossier de config au premier chargement.

Un plugin Rust est un seul fichier C# (.cs) qu’un framework de mods compile et fait tourner dans votre serveur dédié. Les plugins tournent côté serveur uniquement, donc les joueurs n’installent rien. Un serveur vanilla ne peut pas les faire tourner : il faut d’abord Oxide ou Carbon sur le serveur.

Oxide ou Carbon

Les deux chargent le même type de plugin, et un seul peut être sur un serveur à la fois, parce que les deux modifient les mêmes fichiers du jeu.

Oxide (aussi appelé uMod) est le plus ancien. Ses fichiers sont dans le dossier oxide/ du serveur.
Carbon est plus récent et charge aussi les plugins écrits pour Oxide. Ses fichiers sont dans le dossier carbon/.

Crucible Local Server installe l’un ou l’autre pour vous quand vous créez un serveur avec lui, et gère ses plugins dans l’onglet Mods ; voir comment installer Carbon ou Oxide sur un serveur Rust.

Où vont les fichiers de plugin

Quoi	Oxide	Carbon
Plugins (`.cs`)	`oxide/plugins/`	`carbon/plugins/`
Réglages de chaque plugin (`.json`)	`oxide/config/`	`carbon/configs/`
Données qu’un plugin enregistre	`oxide/data/`	`carbon/data/`
Messages d’un plugin, par langue	`oxide/lang/`	`carbon/lang/`
Logs	`oxide/logs/`	`carbon/logs/`

Les dossiers sont à côté de RustDedicated.exe et apparaissent la première fois que le serveur démarre avec le framework installé. Un plugin écrit son fichier de config au premier chargement ; modifiez-le, puis rechargez le plugin.

Charger et recharger un plugin

Déposez un fichier .cs dans le dossier des plugins et le framework le compile et le charge tout seul, sans redémarrage. Modifiez le fichier et il se recharge ; supprimez-le et le plugin est retiré. La console du serveur affiche alors une ligne comme Loaded plugin Hello World v1.0.0 by YourName, ou l’erreur de compilation si le code est faux.

Vous pouvez aussi le faire à la main depuis la console du serveur ou RCON :

Oxide : oxide.load Nom, oxide.reload Nom, oxide.unload Nom, oxide.plugins (chacune marche aussi en o.load, o.reload et ainsi de suite).
Carbon : c.load Nom, c.reload Nom, c.unload Nom, c.plugins.

Nom est le nom du fichier sans .cs. Un serveur qui tourne avec Oxide se déclare comme moddé.

Permissions

La plupart des plugins protègent leurs commandes par des permissions, nommées d’après le plugin (hello.use, kits.admin). Oxide démarre avec deux groupes : default, où se trouve chaque joueur, et admin, pour les admins du serveur.

oxide.grant user <nom ou SteamID> <permission> donne une permission à un joueur.
oxide.grant group default <permission> la donne à tout le monde.
oxide.revoke la retire, sous la même forme.
oxide.usergroup add <nom ou SteamID> <groupe> met un joueur dans un groupe, et oxide.group add <groupe> en crée un nouveau.

Chaque commande Oxide, avec ce qu’elle fait, se trouve à la fin de Commandes de console Rust.

Votre premier plugin

Enregistrez ceci sous HelloWorld.cs dans le dossier des plugins. Il écrit une ligne dans la console au chargement, une pour chaque joueur qui se connecte, et répond à /hello dans le chat.

namespace Oxide.Plugins
{
    [Info("Hello World", "YourName", "1.0.0")]
    [Description("Says hello when a player types /hello in chat.")]
    public class HelloWorld : RustPlugin
    {
        private void OnServerInitialized()
        {
            Puts("Hello World is running.");
        }

        private void OnPlayerConnected(BasePlayer player)
        {
            Puts($"{player.displayName} joined.");
        }

        [ChatCommand("hello")]
        private void HelloCommand(BasePlayer player, string command, string[] args)
        {
            SendReply(player, $"Hello, {player.displayName}!");
        }
    }
}

Ce que fait chaque partie :

Le nom du fichier et le nom de la classe doivent correspondre (HelloWorld.cs, class HelloWorld).
[Info] donne le titre, l’auteur et la version du plugin, que la console affiche au chargement.
Les méthodes nommées d’après un hook s’exécutent quand cet événement se produit dans le jeu : OnServerInitialized une fois que le serveur a fini de démarrer (ou tout de suite s’il tourne déjà), OnPlayerConnected quand un joueur se connecte. Le framework les trouve par leur nom, donc une faute de frappe veut dire que la méthode ne s’exécute jamais, sans erreur.
[ChatCommand("hello")] transforme une méthode en commande de chat. Puts écrit dans la console du serveur ; SendReply envoie un message de chat à un seul joueur.

Le même fichier tourne sur Carbon. La liste complète des hooks et de ce que chacun reçoit se trouve dans la documentation d’Oxide sur docs.oxidemod.com.

Noms et ids utilisés par les plugins

Les plugins désignent les éléments du jeu par leurs noms en jeu, que ce site liste directement depuis le jeu :

Items par shortname (rifle.ak, wood) : liste des items Rust.
Entités par chemin de prefab (assets/prefabs/deployable/large wood storage/box.wooden.large.prefab) : les pages de prefabs de la référence du jeu Rust.
Réglages serveur par nom de convar (server.maxplayers) : variables serveur Rust.

Tester un plugin avant la mise en ligne

Lancez-le d’abord sur une copie locale de votre serveur, avec le même framework et la même map, pour qu’un plugin cassé ne croise jamais vos joueurs. Crucible Local Server en fait tourner un sur votre propre PC avec Oxide ou Carbon installé en un clic.