Plugin Development

Plugin Development Tutorial

What is a Plugin?

A plugin is a separate .NET assembly (.dll file) that contains code to extend the server's features. The server automatically loads these assemblies, allowing you to add new functionality without modifying core code.

Prerequisites

• .NET 8.0 SDK
• C# IDE (Visual Studio 2022, VS Code, or JetBrains Rider)
• UltimateServer source code

Step 1: Create a New Project

dotnet new classlib -n MyAwesomePlugin
cd MyAwesomePlugin

Step 2: Add Reference to Server

Add the IPlugin interface to your project by copying IPlugin.cs and PluginContext.cs from the server project.

Step 3: Implement IPlugin Interface

Create MainPlugin.cs:

using System.Threading.Tasks;
using UltimateServer.Plugins;
namespace MyAwesomePlugin
{
public class MainPlugin : IPlugin
{
public string Name => "My Awesome Plugin";
public string Version => "1.0.0";
    public async Task OnLoadAsync(PluginContext context)
    {
        context.Logger.Log("Hello from My Awesome Plugin! I have been loaded.");
        await Task.CompletedTask;
    }

    public async Task OnUpdateAsync(PluginContext context)
    {
        context.Logger.Log("My Awesome Plugin has been updated.");
        await Task.CompletedTask;
    }

    public async Task OnUnloadAsync(PluginContext context)
    {
        context.Logger.Log("Goodbye! My Awesome Plugin is unloading.");
        await Task.CompletedTask;
    }
}

}

Step 4: Build the Plugin

dotnet build -c Release

Step 5: Deploy the Plugin

1. Navigate to your UltimateServer root directory
2. Create a plugins folder if it doesn't exist
3. Copy MyAwesomePlugin.dll to the plugins folder

Step 6: Test the Plugin

Start the server:

dotnet Server.dll 11001 11002 11003

You should see output like:

🔌 Scanning for plugins in '.../UltimateServer/plugins'
🔌 Found valid assembly: MyAwesomePlugin, Version=1.0.0.0
✅ Loaded plugin: My Awesome Plugin v1.0.0
Hello from My Awesome Plugin! I have been loaded.
🔌 Plugin loading complete. 1 plugins loaded.

Advanced Plugin Features

Accessing Server Services

public async Task OnLoadAsync(PluginContext context)
{
    // Access logger
    context.Logger.Log("Plugin loaded!");
// Access configuration
var authSystem = context.ServiceProvider.GetRequiredService<AuthenticationService>();;

// Register custom commands or events
await Task.CompletedTask;

}

Hot Reloading

Update your plugin code, rebuild, and copy the new DLL to the plugins folder. The server will automatically reload it without restarting.

Best Practices

• Use meaningful plugin names and versions
• Handle exceptions properly in lifecycle methods
• Clean up resources in OnUnloadAsync
• Test plugins thoroughly before deployment