Oxide vs Carbon: Differences, Compatibility and How to Switch

Oxide (also called uMod) and Carbon are two frameworks that add plugin support to a Rust dedicated server. Carbon can load Oxide plugins, so most plugins you find run on both. The real decision comes down to update speed, tooling, hosting support and which one your plugin collection was tested on.

Short comparison

History in brief

Oxide began as a modding framework for several games and became the standard way to run plugins on Rust servers. Its plugin site and documentation are now under the uMod name, and the framework is still referred to as both Oxide and uMod. Most of the plugin ecosystem, tutorials and plugin pages were written against it.

Carbon appeared later as a separate project aimed at Rust servers specifically. Its design goals include faster startup and plugin compilation, lower overhead, and a built-in admin panel. It deliberately accepts Oxide plugins so server owners are not forced to rewrite anything.

Plugin compatibility

Carbon loads Oxide plugins. A typical plugin that:

• declares [Info] and [Description] attributes,
• extends RustPlugin,
• uses standard hooks such as OnPlayerConnected or OnEntityTakeDamage,
• stores settings through Config and data through Interface.Oxide.DataFileSystem,
• uses lang and permission,

works on both without edits. The naming rules are unchanged: the file name matches the main class, as explained in plugin filename must match main class.

Things that can differ:

• Plugins that depend on another plugin through [PluginReference] need that dependency loaded too. See calling other plugins.
• Plugins that rely on obscure internals of Oxide may behave differently.
• Hooks that exist in one framework's patch set may be missing or named differently in the other. Check the console on load for warnings.
• Plugins written specifically for Carbon, using its own APIs, will not load on Oxide.

The practical test is simple: load the plugin, read the console, and exercise its commands and hooks once.

Hook behavior

Both frameworks call plugin methods by hook name and decide which overload to run based on the argument types. The return value semantics of each hook depend on how the game method is patched, so always check the hook page. For example, for CanBuild or OnEntityTakeDamage, any non-null return cancels the default action, which is true or false alike. Learn more in Oxide hooks explained.

Performance claims

Carbon's project advertises lower memory use, faster compile and load times, and less per-hook overhead than Oxide. These claims are plausible given a leaner design, but the effect on your server depends on:

• how many plugins you run and how often their hooks fire,
• hardware and player count,
• whether a few badly written plugins dominate the cost.

On most servers, one plugin doing heavy work in a frequent hook such as OnEntityTakeDamage or OnTick costs far more than framework overhead. Use the slow-hook warnings (see took ms hook performance warning) and the performance guide to measure. If you want to compare, test the same plugin set and the same map on both, under similar load, and compare frame time and warnings.

Admin panel and tooling

Carbon ships with an in-game admin panel for managing plugins, and includes more built-in management commands. Oxide relies on console commands and on plugins you install yourself for admin menus, such as the approach in the admin menu recipe.

Oxide's console tooling covers the essentials: loading, unloading and reloading plugins, plus the permission commands. See Oxide console commands. Carbon accepts the oxide.* commands too, so existing scripts and RCON macros usually keep working.

Update cadence after Rust patches

Rust updates on the first Thursday of the month (the forced wipe) and in smaller patches between. After each update, a framework has to be rebuilt against the new game assemblies, and its hook patches have to still apply. Until that happens, servers may fail to start modded or plugins may break.

Both projects release updates quickly after most patches, but timing varies by patch size and by which hooks changed. Neither can promise a fixed delay. Practical advice:

• Do not update the game server on wipe day before checking that your framework has a matching release.
• Keep a copy of your last working server files.
• After updating, read the console for compile errors and deprecated hooks. See fix Rust plugins after an update and deprecated hook will stop working.
• Follow monthly hook change reports to see which hooks changed.

Plugin authors also need time to update, no matter which framework you use, so a framework release does not mean every plugin is fixed.

Folder differences

The structure is parallel, but the root folder differs.

• Oxide: oxide/plugins, oxide/config, oxide/data, oxide/lang, oxide/logs.
• Carbon: carbon/plugins, carbon/configs, carbon/data, carbon/lang, carbon/logs.

Note config becomes configs on Carbon. Config files keep the form <PluginName>.json. Saving a .cs file into the plugins folder reloads that plugin automatically on both.

Switching from Oxide to Carbon

1. Stop the server and back up the whole server directory, especially oxide/.
2. Install Carbon following its own instructions for your platform, and remove or disable the Oxide files so only one framework patches the game.
3. Copy oxide/plugins/*.cs into carbon/plugins.
4. Copy oxide/config/*.json into carbon/configs.
5. Copy oxide/data contents into carbon/data, including permission data.
6. Copy oxide/lang into carbon/lang, keeping language subfolders.
7. Start the server and read the console. Fix any plugin that fails to load.
8. Verify permissions with oxide.show groups and oxide.show user <name>, then test key commands.

Copy, do not move, so the original stays as a rollback.

Switching from Carbon to Oxide

1. Stop the server and back up the carbon/ folder.
2. Install Oxide and remove Carbon's files completely.
3. Copy plugins, configs (to oxide/config), data and lang back to the Oxide folders.
4. Remove any plugins that use Carbon-only APIs. They will fail to compile on Oxide with errors such as type or namespace not found.
5. Start, read the console, and check permissions with oxide.show.

If a plugin is Carbon-only, you need a replacement or a rewrite.

Permissions and data when switching

Permissions are data, not plugin code. They live in the framework's data folder, so they only move if you copy them. After switching:

• Run oxide.show perms to confirm plugins registered their permissions. See Oxide permissions and groups.
• Run oxide.show groups and check that custom groups and parents exist.
• If a grant is missing, re-grant with oxide.grant group <group> <perm>.

Plugin data files (kits, homes, stats) are ordinary JSON in the data folder. See Rust plugin data files. If a plugin fails with a corrupt file message, see JsonReaderException in data file.

Configs are regenerated with defaults if the file is missing or invalid, which is why copying them matters. See Rust plugin config file.

A sample plugin that works on both

A plugin written to the standard rules runs the same way on both frameworks. It uses only common APIs:

using System.Collections.Generic;

namespace Oxide.Plugins
{
    [Info("Framework Check", "RustPluginGenerator", "1.0.0")]
    [Description("Replies to a chat command with a localized message")]
    public class FrameworkCheck : RustPlugin
    {
        private void LoadDefaultMessages()
        {
            lang.RegisterMessages(new Dictionary<string, string>
            {
                ["Reply"] = "This plugin is running."
            }, this);
        }

        private string Msg(string key, string userId = null, params object[] args) =>
            string.Format(lang.GetMessage(key, this, userId), args);

        [ChatCommand("fwcheck")]
        private void CmdCheck(BasePlayer player, string command, string[] args)
        {
            if (player == null) return;
            player.ChatMessage(Msg("Reply", player.UserIDString));
        }
    }
}

If this loads and answers /fwcheck on a fresh install, the basics of your setup are working.

When to choose which

Choose Oxide when:

• you want the framework most tutorials, plugin pages and support threads assume,
• your host only offers Oxide,
• you depend on a plugin known to behave best there.

Choose Carbon when:

• you want its built-in admin panel and extra tooling,
• load time and overhead matter on a large plugin set and you have measured the gain,
• you are comfortable testing each plugin after switching.

If you are unsure, start with whichever your host supports and keep your plugins in standard form. Because Carbon loads Oxide plugins, you keep the option to switch later. See install Oxide on a Rust server and how to install Rust plugins for setup steps.

Writing plugins that stay portable

• Extend RustPlugin and use documented hooks only.
• Avoid framework-specific APIs unless you target one framework.
• Keep permission names prefixed with the lowercase class name.
• Use Config, lang and Interface.Oxide.DataFileSystem for persistence.
• Test on both if you distribute the plugin.

You can generate a plugin that follows these rules with the plugin generator, and the guide to making a Rust plugin covers the basics.