Guides for Rust plugin owners
How Oxide and Carbon plugins work, explained for server owners: configs, permissions, data files, UI, and the mistakes that break plugins after an update.
- CovalencePlugin vs RustPlugin: Differences and Which to UseRustPlugin is the Rust-specific base class and gives you BasePlayer, [ChatCommand] and the Rust hooks directly. CovalencePlugin exposes the universal IPlayer API, which is meant to run across games. On a Rust-only server, RustPlugin is almost always the better choice. You can convert between the two with `player.IPlayer` and `iplayer.Object as BasePlayer`.4 min read
- How to Debug a Rust Oxide Plugin: Compile Errors, Exceptions and Slow HooksTo debug an Oxide plugin, read the server console and the files in oxide/logs: compile errors appear as "Error while compiling <Name>" with numbered messages and line:column positions, runtime errors appear as "Failed to call hook" with a stack trace. Add targeted Puts or PrintWarning lines, reload with oxide.reload, and test on a local server with a second account. Most crashes in hooks are null references, and slow hooks are reported automatically once they pass 100 ms.10 min read
- How to Give Items to Players in a Rust Plugin (Oxide/Carbon)To give an item in an Oxide plugin, create it with `ItemManager.CreateByName(shortname, amount, skin)` and pass it to `player.GiveItem(item)`, which places it in the inventory or drops it if there is no room. Use `MoveToContainer` when you need a specific container or slot, `GetAmount` and `Take` to remove items, and always null-check the created item.5 min read
- How to Install Oxide on a Rust Dedicated Server (Windows and Linux)To install Oxide, stop your Rust dedicated server, download the Oxide.Rust build for your operating system, extract it over the server root so its files land in RustDedicated_Data/Managed, then start the server and run oxide.version to confirm. Oxide must be reinstalled after every Rust update that replaces the game files, and the Oxide build must match the installed Rust build.7 min read
- How to Install Rust Plugins on an Oxide or Carbon ServerTo install a Rust plugin, upload its .cs file to oxide/plugins (Oxide) or carbon/plugins (Carbon) on your server; the framework compiles and loads it automatically, with no restart needed. After loading, edit the generated config in the config folder and grant the plugin's permissions to the groups that should use it.6 min read
- How to Make a Rust Plugin: Oxide/Carbon C# Tutorial From Zero to a Working PluginA Rust plugin is a single C# file that you drop into oxide/plugins (or carbon/plugins) on a server running Oxide or Carbon; the server compiles and loads it automatically. This tutorial builds a complete playtime reward plugin step by step, covering hooks, chat commands, config, language messages, permissions, data files, reloading and reading compile errors.13 min read
- How to Spawn and Manage Entities in a Rust Plugin (Oxide/Carbon)To spawn an entity in a Rust plugin, call GameManager.server.CreateEntity with a full prefab path, a position and a rotation, then call Spawn() on the result. Entities form a hierarchy (BaseNetworkable, BaseEntity, BaseCombatEntity) that decides which members you can use. This guide covers prefab paths, finding entities, ownership, flags, network updates, killing entities and cleanup on unload.6 min read
- Oxide Chat Commands vs Console Commands: [ChatCommand], [ConsoleCommand] and [Command]An Oxide chat command is a method marked [ChatCommand("name")] that players run by typing /name in chat. A console command is marked [ConsoleCommand("plugin.action")], receives a ConsoleSystem.Arg, and also works from the F1 console, RCON, the server console and CUI buttons. Covalence [Command] is a third, framework-neutral style that uses IPlayer. This guide shows when to use each, with argument validation, permission checks and a working example.5 min read
- Oxide Commands List: Console Commands for Plugins, Permissions and GroupsOxide console commands all start with `oxide.` (or the shorter `o.` alias on many builds) and run from the server console, RCON or an admin's F1 console. They load, unload and reload plugins, grant and revoke permissions, manage groups and show the current state. This reference lists each command with syntax, an example and what it does.4 min read
- Oxide Data Files: Saving and Loading Plugin Data in Rust PluginsOxide data files are JSON files in oxide/data that a plugin reads and writes with Interface.Oxide.DataFileSystem.ReadObject and WriteObject. Use them for runtime state such as player stats, cooldowns and homes, and use the config file for settings the admin edits. Load in Init or OnServerInitialized, save on OnServerSave and Unload, and clear or rotate the data in OnNewSave.7 min read
- Oxide Hooks Explained: How Rust Plugin Hooks WorkAn Oxide hook is a method name that Oxide calls on your plugin when something happens on the Rust server, such as a player connecting or an entity taking damage. Oxide patches the game code to call Interface.CallHook, matches your methods by name, picks overloads by parameter type, and uses the return value to decide whether the default behavior continues.8 min read
- Oxide Lang API: Localizing Rust Plugin MessagesThe Oxide lang API stores plugin text in named keys: register English defaults in LoadDefaultMessages with lang.RegisterMessages, then read them with lang.GetMessage(key, this, userId) and fill placeholders with string.Format. Oxide writes the defaults to oxide/lang/en/<PluginName>.json, where server owners can edit them or add other languages, and each player is served in their own language.5 min read
- Oxide OnEntityTakeDamage: Handling Damage in Rust PluginsOnEntityTakeDamage is the Oxide hook that fires before a Rust entity takes damage, giving a plugin the target and a HitInfo object. You can scale damage with HitInfo.damageTypes, cancel it by returning any non-null value, and classify hits as PvP, PvE, fall or decay by inspecting the target, the initiator and the damage types. Keep the handler cheap, because it runs for almost every hit on the server.7 min read
- Oxide Permissions and Groups: Commands, Inheritance and Plugin CodeOxide permissions are named strings such as `myplugin.use` that plugins register and that server owners grant to players or groups with `oxide.grant`. Groups bundle permissions and players, support a parent for inheritance, and ship with two defaults: `default` and `admin`. Developers register permissions in Init and check them with `permission.UserHasPermission`.6 min read
- Oxide PluginReference: Calling Other Plugins from a Rust PluginAdd a `[PluginReference]` field of type `Plugin` to your class and Oxide fills it with the loaded plugin of the same name, or null when that plugin is not loaded. Call its methods with `Call` or `Call<T>`, always null-check the field first, and use `// Requires: Name` comments when the plugin cannot work without the dependency.5 min read
- Oxide Timer Guide: timer.Once, timer.Every, timer.Repeat and NextTick in Rust PluginsIn Oxide plugins you schedule delayed or repeating code with `timer.Once`, `timer.Every` and `timer.Repeat`, and defer work to the next frame with `NextTick`. Store the returned `Timer` if you need to stop it, and destroy every long-lived timer in `Unload`. An exception inside a timer callback destroys that timer and logs "Failed to run a <seconds> timer".6 min read
- Oxide vs Carbon: Differences, Compatibility and How to SwitchOxide (uMod) and Carbon are both modding frameworks for Rust servers, and Carbon can load plugins written for Oxide, so most plugins run on either one. They differ in project history, internal architecture, folder layout, built-in tooling and how quickly each one updates after a Rust patch. Choose based on plugin needs, hosting support and how you want to handle updates.7 min read
- Rust BasePlayer Plugin Guide: Identity, Lookup, Position, Health, Teams and Null CasesBasePlayer is the class that represents every player and NPC player in a Rust server plugin. Use UserIDString for permissions and data keys, BasePlayer.activePlayerList for online players, and check IsNpc, IsConnected and IsSleeping before acting on a player you did not receive from a connection hook.5 min read
- Rust CUI Tutorial: Build Custom UI Panels in Oxide PluginsCUI is Oxide's server-side API for drawing UI on a player's screen: you build a CuiElementContainer of panels, labels and buttons, send it with CuiHelper.AddUi, and remove it with CuiHelper.DestroyUi. This guide covers anchors, offsets, colors, layers, parent names, cursor control, button commands, updating and cleanup, with a complete plugin that shows a closeable panel.9 min read
- Rust Plugin Config File: How Oxide Configs Work and How to Write OneA Rust plugin config file is a JSON file at oxide/config/<PluginName>.json (carbon/configs on Carbon) that Oxide creates from the plugin's LoadDefaultConfig defaults on first load. Plugin authors map it to a C# class with JsonProperty names, read it with Config.ReadObject, write it with SaveConfig, and add new options in updates by relying on field defaults plus a version field. Server owners edit the file and reload the plugin with oxide.reload.7 min read
- Rust Plugin Development Setup: IDE, DLL References, Test Server and Hot ReloadA working Rust plugin development setup has three parts: an IDE with a class library that references the DLLs from RustDedicated_Data/Managed for IntelliSense, a local dedicated server with Oxide or Carbon installed, and a folder workflow where saving a .cs file in oxide/plugins reloads it automatically. The server compiles your plugin, not the IDE project, so the project only exists for code completion and error checking.8 min read
- Rust Plugin Performance: Hot Hooks, Allocations, Timers and ProfilingRust plugin performance comes down to keeping code in frequently fired hooks (OnEntityTakeDamage, OnTick, OnPlayerInput, OnEntitySpawned) cheap: exit early, avoid LINQ and allocations, cache lookups and permissions, never scan BaseNetworkable.serverEntities repeatedly, and spread heavy work over timers. Oxide logs 'Calling X took Yms' for hooks slower than 100ms, which is your first profiling signal.8 min read
- Rust Plugin Security: Permissions, Input Validation and Backdoor Review for Oxide and CarbonSecure a Rust plugin by checking a permission in every chat and console command, validating all input (amounts, item names, negative numbers), never executing player-supplied strings as console commands, rate limiting repeatable actions and re-checking server-side everything a CUI button sends. When installing third-party plugins, read the source for web requests, hidden permission grants and console command execution before loading it.6 min read
- Rust Plugins Broken After Update: How to Fix Oxide and Carbon PluginsAfter a monthly Rust update, plugins break because the game's code changed underneath them: members were renamed, types changed, or the method an Oxide hook patches was altered. Update Oxide or Carbon first, then read the compile errors, check which hooks changed, and fix or replace the plugins that still fail.8 min read
- Rust Wipe Plugins: Map Wipe and Force Wipe Checklist for Oxide and CarbonOn wipe day, update the Rust server first, then Oxide or Carbon, then read the console for plugin errors before players join. Reset per-wipe data files through the OnNewSave hook, adjust configs, and leave permissions alone because they persist. Test plugins in order: dependencies, core plugins, then gameplay plugins.6 min read