Alloy

About Alloy

Stop writing plugin code in a single file.

Alloy is a folder-plugin compiler for Oxide/uMod and Carbon. It turns a folder of C# source files into a single living plugin — compiled in-memory with Roslyn, loaded without a restart, and hot-reloaded in under a second every time you save.

Write code in your IDE. Hit save. The plugin is already running the new version.

What Is Alloy?

Alloy is a developer toolchain — it does nothing for players on its own. Everything it does is for you: faster iteration, real project structure, and debuggable code on a live server.

A regular Rust plugin is one .cs file. That works until it doesn't — 5,000 lines in, navigating the file becomes the slowest part of development. Alloy adds the folder plugin format: multiple files, nested folders (Core/, UI/, …), conditional compilation, dependencies and assembly references — all described in a single alloy.json manifest. Edit any .cs file in the folder and Alloy recompiles and hot-reloads the plugin automatically.

Classic single-file plugins keep working untouched. Alloy only manages folders that contain an alloy.json.

Core Features

Folder Plugins	A plugin is a folder, not a file. Split code across as many `.cs` files and subfolders as you want — Alloy compiles them into one plugin.
Hot Reload on File Change	A file watcher rebuilds the plugin ~300–500 ms after you save. No restart, no console commands, no waiting.
Atomic Reload with Rollback	A broken edit never kills the running version — the last good build keeps working until you fix the errors.
In-Memory Roslyn Compilation	The real Roslyn compiler, in-process: full C# language features, `#if` directives, glob-based file selection.
Real Stack Traces	PDBs are generated for every build, so exceptions show the actual `File.cs(42,17)` — no more guessing from a merged blob.
Manifest-Driven Configuration	`alloy.json` controls included/excluded files (globstar patterns), plugin dependencies (`requires`), assembly references and conditional-compilation symbols (`define`).
Dependency-Aware Lifecycle	`requires` plugins load in dependency order. A plugin whose dependency is missing waits instead of failing — and loads itself the moment the dependency appears. Unloading a dependency unloads everything that depends on it.
Conditional Compilation	Alloy always defines `ALLOY` plus `OXIDE` or `CARBON` depending on the framework — one codebase targets both.
One Core, Both Frameworks	A shared `Alloy.Core` (netstandard2.0) with thin adapters per framework — identical behavior and manifest format on Oxide and Carbon.
Console Commands	`alloy.list`, `alloy.load`, `alloy.unload`, `alloy.reload`, `alloy.build`, `alloy.verbose` — full lifecycle control without leaving the console.

The Folder Format

oxide/plugins/MyPlugin/
├── alloy.json          ← manifest (required)
├── MyPlugin.cs         ← entry class
├── Core/
│   └── Storage.cs
└── UI/
    └── Panels.cs

{
  "name": "MyPlugin",
  "files": ["**/*.cs"],
  "exclude": ["Tests/**"],
  "requires":   ["ServerPrefabs"],
  "references": ["0Harmony", "Facepunch.Steamworks"],
  "define": ["DEBUG"],
  "reload": { "watch": true, "debounceMs": 500 }
}

Dependencies and assembly references are declared only in the manifest — Alloy does not parse // Requires: / // Reference: directives in sources. [Info]/[Description] attributes remain the source of plugin metadata — the manifest never duplicates them.

Debugging

Compiler Diagnostics	Real folder-relative paths: `MyPlugin/UI/Panels.cs(42,17): error CS1002: ; expected` — in the console and in the log.
Runtime Exceptions	Exceptions point to real files and lines thanks to generated PDBs.
Log File	`logs/Alloy.log` — Carbon FileLogger format: `[yyyy.MM.dd HH:mm:ss] message`.
Verbose Mode	`alloy.verbose on` — detailed pipeline logging: scan, globs, compilation, registration, watcher events.

Installation

Download Alloy.zip from this page and extract it. Inside are two folders — Oxide/ and Carbon/ — that mirror your server's directory layout. Pick the one for your framework and copy its contents into your server's root folder, then restart the server. The two folders never conflict.

Oxide

Copy the contents of Oxide/RustDedicated_Data/Managed/ into RustDedicated_Data/Managed/: Oxide.Ext.Alloy.dll, Alloy.Core.dll and the bundled Roslyn assemblies (Microsoft.CodeAnalysis.dll, Microsoft.CodeAnalysis.CSharp.dll, System.Collections.Immutable.dll, System.Reflection.Metadata.dll, …).
Restart the server — the log will show Alloy initialized.

Carbon

Copy the contents of Carbon/carbon/extensions/ into carbon/extensions/: Alloy.dll and Alloy.Core.dll. Roslyn is already loaded by Carbon — no extra DLLs needed.
Restart the server.
Alloy plugins are registered in their own Alloy ModLoader package — one group in Carbon's plugin lists, never mixed with single-file plugins.

Console Commands

Command	Action
`alloy.list`	Folder plugins: state, folder name, file count, build time
`alloy.load <name>`	Build and register the plugin
`alloy.unload <name>`	Disable and unload
`alloy.reload <name>`	Rebuild with atomic rollback
`alloy.build <name>`	Compile only — verify errors without loading
`alloy.verbose on\|off`	Toggle detailed pipeline logging

Perfect For

Plugins that have outgrown a single .cs file
Iterating on a live server without restarts
Sharing one codebase between Oxide and Carbon builds of the same plugin
Structured plugin projects with internal modules (Core, UI, Data…)
Debugging with real file/line stack traces
Framework and library plugins with complex internals

Good to Know

Alloy is a development tool — run it on your dev/staging server, not as a player-facing feature.
Only folders with an alloy.json are managed; everything else behaves exactly as before.
No // Requires: / // Reference: comment parsing — the manifest is the single source of truth by design.

Alloy is a core developer tool for Rust plugin authors who want real project structure and instant feedback on a live server.

Folder plugins. One-second iteration. Real stack traces. Development the way it should have been.