Rust plugins: Oxide and Carbon basics

A Rust plugin is one C# file (.cs) that a modding framework compiles and runs inside your dedicated server. Plugins run on the server only, so players never install anything. A vanilla server cannot run them: you need Oxide or Carbon on the server first.

Oxide or Carbon

Both load the same kind of plugin, and only one can be on a server at a time, because both patch the same game files.

• Oxide (also called uMod) is the long-standing one. Its files live in the oxide/ folder of the server.
• Carbon is newer and loads plugins written for Oxide as well. Its files live in the carbon/ folder.

Crucible Local Server installs either one per server and keeps their plugins apart; see Mods and plugins (Carbon and Oxide).

Where plugin files go

What	Oxide	Carbon
Plugins (.cs)	oxide/plugins/	carbon/plugins/
Each plugin’s settings (.json)	oxide/config/	carbon/configs/
Data a plugin saves	oxide/data/	carbon/data/
A plugin’s messages, per language	oxide/lang/	carbon/lang/
Logs	oxide/logs/	carbon/logs/

The folders sit next to RustDedicated.exe and appear the first time the server starts with the framework installed. A plugin writes its config file the first time it loads; edit it, then reload the plugin.

Load, reload and unload

Drop a .cs file into the plugins folder and the framework compiles and loads it on its own, without a restart. Change the file and it reloads; delete it and it unloads. The server console then shows a line such as Loaded plugin Hello World v1.0.0 by YourName, or the compile error if the code is wrong.

You can also do it by hand from the server console or RCON:

• Oxide: oxide.load Name, oxide.reload Name, oxide.unload Name, oxide.plugins (each also works as o.load, o.reload and so on).
• Carbon: c.load Name, c.reload Name, c.unload Name, c.plugins.

Name is the file name without .cs. A server running Oxide marks itself as modded.

Permissions

Most plugins gate their commands behind permissions, named after the plugin (hello.use, kits.admin). Oxide starts with two groups: default, which every player is in, and admin, for the server’s admins.

• oxide.grant user <name or SteamID> <permission> gives one player a permission.
• oxide.grant group default <permission> gives it to everyone.
• oxide.revoke takes it back, in the same form.
• oxide.usergroup add <name or SteamID> <group> puts a player in a group, and oxide.group add <group> makes a new one.

Every Oxide command, with what it does, is at the end of Rust console commands.

Your first plugin

Save this as HelloWorld.cs in the plugins folder. It writes a line to the console when it loads, one for every player who joins, and answers /hello in 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}!");
        }
    }
}

What each part does:

• The file name and the class name must match (HelloWorld.cs, class HelloWorld).
• [Info] gives the plugin’s title, author and version, which the console shows when it loads.
• Methods named after a hook run when that thing happens in the game: OnServerInitialized once the server has finished starting (or straight away if it is already running), OnPlayerConnected when a player joins. The framework finds them by name, so a typo means the method never runs, with no error.
• [ChatCommand("hello")] turns a method into a chat command. Puts writes to the server console; SendReply sends a chat message to one player.

The same file runs on Carbon. The full list of hooks and what each one receives is in the Oxide documentation at docs.oxidemod.com.

Names and ids plugins use

Plugins refer to game things by their in-game names, which this site lists straight from the game:

• Items by shortname (rifle.ak, wood): Rust item list.
• Entities by prefab path (assets/prefabs/deployable/large wood storage/box.wooden.large.prefab): the prefab pages under Rust game reference.
• Server settings by convar name (server.maxplayers): Rust server variables.

Test a plugin before it goes live

Run it on a local copy of your server first, with the same framework and the same map, so a broken plugin never meets your players. Crucible Local Server runs one on your own PC with Oxide or Carbon installed in a click.