Getting Started
Install the Plugin Template
With the .NET 10.0 SDK installed and dotnet on your PATH, install the plugin template, then run it with your plugin's details:
dotnet new install SwiftlyS2.CS2.PluginTemplate
dotnet new swplugin -n MyPlugin --PluginName "My Plugin" --PluginVersion "1.0.0" --PluginAuthor "Author" --PluginDescription "My first SwiftlyS2 plugin"-n becomes the plugin's Id, namespace, class name, assembly name and
output folder. The other flags only fill in APIPluginMetadata
and can be edited afterwards.
Generated project layout:
MyPlugin/
├── examples/
│ ├── Commands.example.cs
│ ├── Events.example.cs
│ ├── GameEvents.example.cs
│ ├── HookAndCallNativeFunctions.example.cs
│ ├── NetMessage.example.cs
│ └── SoundEvent.example.cs
├── resources/
│ ├── gamedata/
│ │ ├── offsets.jsonc
│ │ ├── patches.jsonc
│ │ └── signatures.jsonc
│ ├── templates/
│ └── translations/
│ └── en.jsonc
├── MyPlugin.cs
├── MyPlugin.csproj
└── README.md
examples/ is excluded from compilation by default (<Compile Remove="examples\**\*.cs" />) - it's reference material, not part of your plugin.
resources/gamedata, resources/templates and resources/translations
copy to the output directory on build. Each plugin manages its own
resources/gamedata, independently from others.
A freshly generated project may not reference the latest release - bump it in your .csproj if needed: <PackageReference Include="SwiftlyS2.CS2" Version="*" ExcludeAssets="runtime" PrivateAssets="all" />. * tracks latest stable; pin a version (e.g. 1.0.3) for reproducible builds, or use *-* for preview releases.
Main plugin class:
using SwiftlyS2.Shared.Plugins;
using SwiftlyS2.Shared;
namespace MyPlugin;
[PluginMetadata(Id = "MyPlugin", Version = "1.0.0", Name = "My Plugin", Author = "Author", Description = "My first SwiftlyS2 plugin")]
public partial class MyPlugin : BasePlugin
{
public MyPlugin(ISwiftlyCore core) : base(core)
{
}
public override void Load(bool hotReload)
{
}
public override void Unload()
{
}
}Plugin Metadata
[PluginMetadata] supplies the metadata SwiftlyS2 reports for your plugin, at runtime through APIIPluginManager.GetPluginMetadata and APIIPluginManager.GetAllPluginMetadata (see the member table under Managing Plugins at Runtime). Id and Version are required; Name falls back to Id when it isn't set, and the other properties have defaults:
| Property | Required | Default |
|---|---|---|
Id | yes | - |
Version | yes | - |
Name | no | the value of Id |
Author | no | "Anonymous" |
Description | no | "No further description." |
Website | no | empty string |
MinimumAPIVersion | no | "0.0.0" |
See APIPluginMetadata for the full member list.
Plugin Lifecycle
Your plugin class derives from APIBasePlugin (which implements APIIPlugin) and takes APIISwiftlyCore as a constructor parameter. APIBasePlugin stores it in the protected Core property, which only the base constructor assigns - derived classes read it (see Swiftly Core).
Load and Unload are abstract and must both be overridden. The remaining callbacks are virtual no-ops, overridden only when you need them:
| Member | Called |
|---|---|
Load(bool hotReload) | when the plugin is loaded. hotReload is true when the plugin is loaded as part of a reload rather than the server's initial load of it. |
Unload() | when the plugin is unloaded - also in a hot reload, before Load runs again. Undo everything you set up in Load. |
ConfigureSharedInterface(IInterfaceManager) | to register the interfaces your plugin provides, see Shared API. |
UseSharedInterface(IInterfaceManager) | to resolve interfaces provided by other plugins. |
OnSharedInterfaceInjected(IInterfaceManager) | once shared interfaces have been resolved. |
OnAllPluginsLoaded() | once every plugin on the server has finished loading. |
public override void Load(bool hotReload)
{
Core.Logger.LogInformation("Loaded. Hot reload: {HotReload}", hotReload);
}
public override void Unload()
{
// Release anything you set up in Load.
}
public override void ConfigureSharedInterface(IInterfaceManager interfaceManager)
{
// Register the interfaces this plugin provides.
}The three shared interface callbacks run in the order listed above, and they re-run whenever the plugin set changes - don't assume they only fire once at startup. See Shared API for what to do inside each of them.
Managing Plugins at Runtime
Core.PluginManager (APIISwiftlyCore.PluginManager, type APIIPluginManager) loads, unloads and reloads plugins by ID while the server runs - the programmatic equivalent of a hot reload, which runs Unload and then Load with hotReload set to true:
| Member | Signature | Returns |
|---|---|---|
LoadPlugin | bool LoadPlugin(string pluginId, bool silent = false) | whether the plugin was loaded successfully |
UnloadPlugin | bool UnloadPlugin(string pluginId, bool silent = false) | whether the plugin was unloaded successfully |
ReloadPlugin | bool ReloadPlugin(string pluginId, bool silent = false) | whether the plugin was reloaded successfully |
GetPluginStatus | PluginStatus? GetPluginStatus(string pluginId) | the plugin's status |
GetPluginMetadata | PluginMetadata? GetPluginMetadata(string pluginId) | the plugin's metadata |
GetPluginPath | string? GetPluginPath(string pluginId) | the plugin's path |
GetPluginPaths | Dictionary<string, string> GetPluginPaths() | every plugin path, keyed by plugin ID |
GetAllPluginStatuses | Dictionary<string, PluginStatus> GetAllPluginStatuses() | every plugin status, keyed by plugin ID |
GetAllPluginMetadata | Dictionary<string, PluginMetadata> GetAllPluginMetadata() | every plugin's metadata, keyed by plugin ID |
GetAllPlugins | IEnumerable<string> GetAllPlugins() | every plugin ID |
silent suppresses error messages for the three boolean members. GetPluginStatus, GetPluginMetadata and GetPluginPath return null for an unknown plugin ID, while the dictionary-returning members are keyed by plugin ID. GetPluginStatus reports a APIPluginStatus: Loaded, Unloaded, Loading, Error or Indeterminate.
if (Core.PluginManager.ReloadPlugin("EconomyPlugin"))
{
Core.Logger.LogInformation("EconomyPlugin reloaded.");
}
else
{
Core.Logger.LogWarning("EconomyPlugin could not be reloaded (status: {Status}).", Core.PluginManager.GetPluginStatus("EconomyPlugin"));
}Injecting Services into the Plugin
Besides the constructor, a service can be injected into a member: APISwiftlyInject (SwiftlyS2.Shared) is parameterless and applies to fields and properties, and SwiftlyS2 assigns the service to the marked member.
public partial class MyPlugin : BasePlugin
{
[SwiftlyInject] private ICommandService _commands = null!;
public MyPlugin(ISwiftlyCore core) : base(core)
{
}
}Publishing
dotnet publishThis outputs the packaged plugin to build/publish/<PluginId>/ and a ready-to-share build/<AssemblyName>.zip alongside it.
To test locally, copy build/publish/<PluginId>/ into your server's addons/swiftlys2/plugins/<PluginId>/. Use the .zip for releases.
Next Steps
The template's examples/ folder covers commands, core events, game events, native function hooking, net messages and sound events - the rest of this Development section covers each system in more depth. Read the Dependency Injection guide before writing logic, since SwiftlyS2 plugins favor constructor-based DI over static/global state.