Rust modding resources
On this page
- Start here
- Writing your first plugin
- How a plugin runs: the Oxide developer guides
- In-game panels (CUI)
- Carbon developer documentation
- Hooks
- Patching and reading game code
- Rust updates, items and entities
- Running and testing a server
- Custom maps
- C#, code analysis and config files
- On this site
- Get help
Modding Rust means reading in a lot of places: two plugin frameworks, a game wiki, a decompiler, a patching library, a style guide or two. This is every link we found useful, in one place and grouped by what you are trying to do. Each has one line of our own saying what it is for and who it is for.
148 links in 12 groups. Each was opened on and answered. Two sites show a browser check to scripts and are marked may need a browser: open those in a normal browser. Links open in a new tab, except the ones on this site.
- Server owner
- Everyone
- Tool
Start here
The front doors. If you only bookmark five things, bookmark these.
- Oxide documentation Everyone The official manual for the Oxide framework: running it as an owner, writing plugins for it, and the list of hooks.
- Carbon documentation Everyone The manual for the Carbon framework, with owner guides, developer guides and lists of items, entities and commands (docs.carbonmod.gg points here).
- uMod Everyone may need a browser The long-running library of free Rust plugins, which also keeps documentation pages. The site asks for a browser check, so open it in a normal browser rather than a script.
- Rust wiki Everyone Facepunch's own wiki: creating a server, modding basics, custom maps and a page for each item.
- Modding, on the Rust wiki The wiki's own reading order for a new modder: overview, tools, C# basics, entities, hooks, items.
Writing your first plugin
The Oxide developer guides are the most complete plain-English material there is, and Carbon plugins follow the same shape. Read them roughly in this order.
- Getting started with plugin development A short orientation for a new author: what a plugin can do and what the later guides cover.
- Setting up a development environment Which editor, which game files and which references to put in a project before you write any code.
- Your first plugin A step-by-step tutorial that builds a small working plugin. It saves the config right after loading it; a load that never rewrites the owner's file is the better habit.
- Plugin attributes What Info, Description, command, permission, hook and patch attributes do, with the exact spelling for each.
- Plugin guidelines The framework's own style guide: names, comments, structure, version numbers and the changelog. Most of our review rules lean on it.
- Best practices A short list of habits: be careful with player data, keep up with updates, test under load, name your constants.
- Modding tools Facepunch's advice on which editor and source-control tools to start with.
- C# basics A primer on the parts of C# you meet first when modding Rust. Good if you have never written C# before.
- C# formatting How the wiki suggests laying out C# code so other people can read it.
- Coroutines, on the Rust wiki Facepunch's explanation of coroutines, the way to spread work across several frames.
How a plugin runs: the Oxide developer guides
One page per topic. Read the one you need when you need it: they are short.
- Plugin lifecycle What runs when a plugin loads, starts, reloads and unloads, and where reading config or calling another plugin belongs.
- Server lifecycle The order the server saves data and shuts things down, which tells you when it is too late to save yours.
- Permissions Registering a permission, checking it, and how groups hand it out.
- Timers One-shot and repeating timers, and how to stop them.
- Web requests Calling a web service without freezing the server: the call, the callback and the status codes to look at.
- Data storage Saving config and data as JSON, and the attributes that decide what gets written.
- Databases Using SQL from a plugin through the framework's callback-based calls, with parameters instead of pasted-in text.
- Pooling Borrowing and returning reusable lists and objects to cut down on garbage, and the mistakes that leak them.
- Coroutines What a coroutine can and cannot do on the server's main thread.
- Target frameworks Which .NET versions each part of Oxide is built for, which matters when you set up a project.
- Oxide core reference Everyone Reference pages for the built-in libraries (timers, permissions, web requests) and the console commands.
- Plugin commands (oxide.load, oxide.reload and friends) Server owner Loading, unloading and reloading plugins from the console, and listing what is running.
- Permission commands Server owner Granting and removing permissions and groups from the console.
- Miscellaneous commands Server owner The remaining Oxide console commands, such as saving data.
- Glossary Everyone Plain definitions of the words the Oxide docs use.
In-game panels (CUI)
CUI is how a plugin draws panels, buttons and lists on a player's screen. It mirrors Unity's UI system, so the Unity pages below explain what the CUI names mean.
- CUI class reference How elements are named and parented, and every component you can put on one: position, image, text, button, input, scroll view and more.
- CUI examples The index of runnable CUI samples.
- Example: position versus resolution Shows what happens to a panel at different screen sizes and why anchors scale where pixel offsets do not.
- Example: countdown and update A countdown that ticks on the player's screen, then changes other elements in place with no redraw.
- Example: draggable panel A panel the player can drag around.
- Example: grid Simple elements arranged by a grid layout instead of hand-placed.
- Example: grid of buttons A grid of buttons from the grid layout component.
- Example: vertical layout Stacking rows with the vertical layout and size fitter so you do not place each row by hand.
- Example: scroll view The basic scrolling list, the answer to Previous and Next page buttons.
- Example: scroll view with layout A scrolling list whose rows the client lays out and resizes, updated in place.
- Lightweight UI (Carbon) Carbon's builder for panels sent in a compact form. It works on Carbon only.
- Layout Designer (Carbon) Tool A visual editor for CUI layouts that gives you the exact position numbers to paste into code.
- Unity UI manual The Unity documentation CUI mirrors. When a CUI component confuses you, read the Unity page of the same name.
- Unity: Rect Transform How anchors, pivots and offsets place an element: the idea behind every CUI position.
- Unity: basic layout Anchoring and positioning explained with pictures.
- Unity: canvas The surface UI is drawn on, and how draw order works.
- Unity: scroll rect The component behind scroll views: content, viewport, clamping and scrollbars.
- Unity: vertical layout group Stacks child elements top to bottom with spacing and padding.
- Unity: grid layout group Arranges children in rows and columns of a fixed cell size.
- Unity: content size fitter Makes a panel grow to fit what is inside it, which scroll content needs.
Carbon developer documentation
Carbon runs Oxide-style plugins and adds its own features. These pages cover what is different or extra.
- Creating hooks How Carbon calls hooks, and how to patch a game method with Harmony using an automatic patch class.
- Creating your first plugin The Carbon version of a first plugin: which base class and namespace suit a Carbon-only plugin and an Oxide-compatible one.
- Creating your project Setting up a Visual Studio project against Carbon's files, including the mode that writes out the patched game assemblies.
- Commands Chat, console, RCON and universal command attributes, plus permission, group and cooldown attributes.
- Conditionals Compile-time symbols so one file can serve both frameworks, or an upcoming Rust build.
- Permissions Registering and checking permissions and managing groups in Carbon.
- Timers Carbon's timers, including how to stop a stored one.
- Async shutdown Doing asynchronous clean-up, such as a final web call, when the server shuts down or restarts.
- Client entities Entities that exist only on selected players' screens, with no server cost.
- Zip script packages Shipping one plugin as several source files in a single .cszip.
- Extensions Library code shared by several plugins, loaded as a Carbon extension.
- Vault Keeping secrets such as API keys out of plain-text config files.
- Mono profiler Measuring how often plugin code is called and how long it takes, and what that costs while it runs.
- Bridge Sending data between servers over Carbon's bridge connection.
- Custom vitals Adding your own status icons to the player's screen.
- Modifiers Adding fields to game classes from a JSON file, so data can ride along with an entity.
- Image database module Downloading, storing and looking up images for use in panels.
- Modal module A ready-made pop-up form with typed fields and confirm or cancel.
- Colour picker module A ready-made colour chooser for your panels.
- Date picker module A ready-made date chooser for your panels.
- File picker module A ready-made file chooser limited to a folder you name.
- Porting from Oxide Everyone What changes when you move from Oxide to Carbon: command names, folders and how hooks fire.
- Local server hosting Running a server on your own PC so you can test plugins as you write them.
- Carbon tutorials Everyone Carbon's blog posts and tutorials.
- Carbon on GitHub Carbon's source code, for when the docs do not answer the question.
Hooks
A hook is the framework telling your plugin that something happened, or asking whether it may. These are the lists to look in.
- Oxide hooks reference About 700 hooks in around 30 categories, one page each, with the parameters and a code sample.
- Carbon hooks reference Carbon's own hook list. Check it when a hook seems to behave differently from its Oxide page.
- Hooks, on the Rust wiki A plain-language explanation of what a hook is and how a framework finds yours.
- Oxide.Rust on GitHub Where Oxide's Rust hooks are built. Read it to see exactly when a hook fires.
Patching and reading game code
When no hook exists you patch the game with Harmony, and before you patch you read what the game method really does.
- Harmony documentation Tool The library Oxide and Carbon both use to change game methods from outside.
- Harmony: introduction What patching is and the words the rest of the docs use.
- Harmony: basics The first patch end to end.
- Harmony: annotations The attributes that name which method a patch targets.
- Harmony: prefix Code that runs before the original method and can skip it.
- Harmony: postfix Code that runs after the original and can read or change its result.
- Harmony: finalizer Code that handles an exception thrown by the original.
- Harmony: transpiler Rewriting the method's instructions. Powerful and fragile: try a prefix or postfix first.
- Harmony on GitHub Tool The source, the issue list and the releases.
- The publicizer How the game's private members become reachable from plugins, and which assemblies are left alone.
- Using a decompiler How to read the game's code to learn what a method does before you hook or patch it.
- ILSpy Tool A free decompiler for reading the game's code, including Assembly-CSharp.dll, in a window.
- ILSpy releases Tool Downloads for ILSpy.
- ilspycmd Tool The command-line version of ILSpy, installed as a dotnet tool. Handy for decompiling after every game update from a script.
- ilspycmd on GitHub Tool The command-line tool's source and usage notes.
- .NET downloads Tool The SDK you need for dotnet tools and for compiling a plugin on your own machine.
Rust updates, items and entities
Plugins break when the game changes, and they need the game's exact names. Look things up here instead of guessing.
- Facepunch commits for Rust Everyone The developers' running list of changes to Rust: the first place to see what an update touched.
- Carbon release notes Everyone What changed in each Carbon release.
- Items reference Everyone A browsable list of the game's items. Use it to find the exact name to put in code or a command.
- Entities reference A browsable list of the game's entities.
- Prefabs reference A browsable list of prefab paths, the names you use to spawn things.
- Items overview How item definitions, item mods, blueprints and containers fit together.
- A wiki item page (bandage) Everyone The wiki has one page per item at /rust/item/ followed by the item's short name. There is no single item list page there, so find the short name in the items reference above.
- Item mods The small components that give an item extra behaviour.
- Entities, on the Rust wiki Spawning an entity: the prefab name, position and rotation.
- Modding overview The difference between entities, which are networked and can be changed, and world prefabs, which are not.
Running and testing a server
Whether you run the server for players or only to test your plugin, these cover the ground.
- Creating a server Server owner Facepunch's own steps and hardware needs for a dedicated server on Windows, Linux or Mac.
- Getting started with your server Server owner Loose facts about the server folder and the identity that do not have a page of their own.
- SteamCMD Tool may need a browser Valve's command-line tool for installing and updating the Rust server files. The wiki shows a browser check, so open it in a normal browser.
- Oxide for owners Server owner The framework's own setup guide for server owners.
- Carbon for owners Server owner Installing Carbon and the first things to know as a server owner.
- Rust console commands Server owner A list of the game's built-in console commands.
- Rust console variables Server owner A list of the game's server settings.
- Carbon commands Server owner A list of Carbon's own console commands.
- Carbon variables Server owner Carbon's own settings, which extend what the game offers.
- Carbon switches Server owner The list of Carbon's startup switches.
- Server DNS records Server owner Pointing a domain name at your server so players can type a name instead of an address.
- Custom server icon Server owner Setting the picture shown in the server browser.
- Profiler, on the Rust wiki Server owner Starting the server with the profiler switch and taking snapshots, with the cost of leaving it on.
- Carbon control panel Tool A browser dashboard for a Carbon server: console, chat, players, permissions and plugins.
- Carbon profiler panel Tool The in-game profiler tab, in a browser.
Custom maps
A small shelf for anyone making or hosting their own map.
- Custom maps Everyone The overview of making your own world: terrain, splat layers and topology.
- Map editors Tool The editors Facepunch points to, and what each is good for.
- Hosting a custom map Server owner The one server setting you need to serve a custom map, and the details around it.
- Topology The list of ground characteristics, such as where water is salty or where nodes can spawn.
- Map data What a .map file holds and what a procedural map is generated from.
- Map FAQ and troubleshooting Common map-making problems, including the world mismatch error after you change a map.
C#, code analysis and config files
General-purpose references that keep coming up when you read someone's plugin or write your own.
- C# coding conventions Microsoft's baseline for how C# is laid out and written.
- C# identifier names Naming rules for classes, fields, methods and locals.
- XML documentation comments How the three-slash summary, param and returns comments work.
- Code analysis overview Tool What the .NET analyzers are and how to switch them on in a project.
- Code quality rules index The full list of CA rules, each with an explanation and a fix.
- Performance rules The performance subset of the CA rules.
- CA1853: unnecessary ContainsKey call Why asking a dictionary whether a key exists before removing it does the lookup twice.
- CA1854: prefer TryGetValue Why TryGetValue beats ContainsKey followed by an index read.
- Json.NET documentation The JSON library behind plugin config and data files.
- Json.NET serialization attributes The attributes that control what is written to a config file and under which name.
- Json.NET JsonProperty Giving a field a readable name in the file that differs from its C# name.
- Json.NET ObjectCreationHandling The setting that decides whether a loaded list replaces the default list or is added to it.
- Semantic Versioning What the three numbers in a plugin's version should mean.
- Keep a Changelog A plain format for the changelog file that goes beside a plugin.
On this site
Our own guides and tools, written from servers we run.
- Set up a Rust server on a VPS or dedicated box Server owner Ubuntu from first login to a running Carbon or Oxide server, with every command.
- Set it up with AI Server owner How to use an AI assistant for server setup with care, and two prompts to copy.
- Game host or your own server? Server owner An honest comparison, with measured numbers on the hardware that matters.
- What reviewers check in a Rust plugin The rules a careful reviewer holds a plugin to, each with the source behind it.
- How the checks work Tool What the directory's automated check looks for in every hosted file, and what it leaves to a person.
- The compile board Tool Which hosted plugins compile on the current Rust build, with and without compatibility shims.
- How to check a mod before you run it Server owner A buyer's checklist, including a prompt for having an AI read the source.
- Outside Unsafe Base: what changed and why A worked example of reviewing a community plugin, fixing it and testing it on a real base.
Know a good link that is missing? Say so on the Help board and it will be added. The rules we hold plugins to are on What reviewers check in a Rust plugin.
