Getting Started
namespace Oxide.Plugins
{
[Info("EpicStuff", "Unknown", 0.1)]
[Description("Makes epic stuff happen")]
class EpicStuff : BlockstormPlugin
{
// The rest of the code and magic
}
}
The Title variable is what defines your plugin. This should be a unique codename or short description such as Pets.
The Author variable is used to show who made the plugin. This should match your OxideMod.org username if releasing.
The Version variable is used to tell if the plugin is outdated or not, and is incremented with each release. Semantic Versioning recommended.
The Description variable helps explain to users what your plugin does, in case the title isn't enough. Make it good, but not too long!
Universal Hooks
Available for all supported games
Init
void Init()
{
Puts("Init works!");
}
- Called when a plugin is being initialized
- Other plugins may or may not be present, dependant on load order
- No return behavior
Loaded
void Loaded()
{
Puts("Loaded works!");
}
- Called when a plugin has finished loading
- Other plugins may or may not be present, dependant on load order
- No return behavior
Unload
void Unload()
{
Puts("Save files, destroy timers, etc");
}
- Called when a plugin is being unloaded
- No return behavior
LoadDefaultConfig
protected override void LoadDefaultConfig()
{
Puts("Default configuration created");
}
- Called when the config for a plugin should be initialized
- Only called if the config file does not already exist
- No return behavior
LoadDefaultMessages
private new void LoadDefaultMessages()
{
lang.RegisterMessages(new Dictionary<string, string>
{
["Example"] = "This is an example message!",
["AnotherExample"] = "Here is another example"
}, this);
}
- Called when the localization for a plugin should be registered
- No return behavior
OnFrame
void OnFrame()
{
Puts("OnFrame works!");
}
- Called each frame
- No return behavior
OnPluginLoaded
void OnPluginLoaded(Plugin name)
{
Puts($"Plugin '{name}' has been loaded");
}
- Called when a plugin has been loaded
- No return behavior
OnPluginUnloaded
void OnPluginUnloaded(Plugin name)
{
Puts($"Plugin '{name}' has been unloaded");
}
- Called when a plugin has been unloaded
- No return behavior
OnServerInitialized
void OnServerInitialized()
{
Puts("OnServerInitialized works!");
}
- Called after the server startup has been completed and is awaiting connections
- No return behavior
OnServerSave
void OnServerSave()
{
Puts("OnServerSave works!");
}
- Called before the server saves and shuts down
- No return behavior
OnPermissionRegistered
void OnPermissionRegistered(string name, Plugin owner)
{
Puts($"Permission '{name}' has been registered {(owner != null ? $"for {owner.Title}" : "")}");
}
- Called when a permission has been registered
- No return behavior
OnGroupPermissionGranted
void OnGroupPermissionGranted(string name, string perm)
{
Puts($"Group '{name}' granted permission: {perm}");
}
- Called when a permission has been granted to a group
- No return behavior
OnGroupPermissionRevoked
void OnGroupPermissionRevoked(string name, string perm)
{
Puts($"Group '{name}' revoked permission: {perm}");
}
- Called when a permission has been revoked from a group
- No return behavior
OnGroupCreated
void OnGroupCreated(string name)
{
Puts($"Group '{name}' created!");
}
- Called when a group has been created successfully
- No return behavior
OnGroupDeleted
void OnGroupDeleted(string name)
{
Puts($"Group '{name}' deleted!");
}
- Called when a group has been deleted successfully
- No return behavior
OnGroupTitleSet
void OnGroupTitleSet(string name, string title)
{
Puts($"Title '{title}' set on group '{name}'");
}
- Called when a group title has been updated
- No return behavior
OnGroupRankSet
void OnGroupRankSet(string name, int rank)
{
Puts($"Rank '{rank}' set on group '{name}'");
}
- Called when a group rank has been updated
- No return behavior
OnGroupParentSet
void OnGroupParentSet(string name, string parent)
{
Puts($"Parent '{parent}' set on group '{name}'");
}
- Called when a group parent has been updated
- No return behavior
OnUserNameUpdated
void OnUserNameUpdated(string id, string oldName, string newName)
{
Puts($"Player name changed from {oldName} to {newName} for ID {id}");
}
- Called when the LastSeenNickname has been updated in oxides datafile
- No return behavior
OnUserGroupAdded
void OnUserGroupAdded(string id, string name)
{
Puts($"User '{id}' added to group: {name}");
}
- Called when a player has been added to a group
- No return behavior
OnUserGroupRemoved
void OnUserGroupRemoved(string id, string name)
{
Puts($"Player '{id}' removed from group: {name}");
}
- Called when a player has been removed from a group
- No return behavior
OnUserPermissionGranted
void OnUserPermissionGranted(string id, string perm)
{
Puts($"Player '{id}' granted permission: {perm}");
}
- Called when a permission has been granted to a player
- No return behavior
OnUserPermissionRevoked
void OnUserPermissionRevoked(string id, string perm)
{
Puts($"Player '{id}' revoked permission: {perm}");
}
- Called when a permission has been revoked from a player
- No return behavior
OnUserKicked
void OnUserKicked(IPlayer player, string reason)
{
Puts($"Player {player.Name} ({player.Id}) was kicked");
}
- Called when a player has been kicked from the server
- No return behavior
OnUserBanned
void OnUserBanned(string name, string id, string address, string reason)
{
Puts($"Player {name} ({id}) was banned: {reason}");
}
- Called when a player has been banned from the server
- No return behavior
OnUserUnbanned
void OnUserUnbanned(string name, string id, string ip)
{
Puts($"Player {name} ({id}) was unbanned");
}
- Called when a player has been unbanned from the server
- No return behavior
Timers (Basic)
Timers are great for delaying code, allowing it to be run later.
Single timer
timer.Once(3f, () =>
{
Puts("Hello world!")
});
Executes the specified function once after the specified delay.
Repeating timer
timer.Repeat(5f, 0, () =>
{
Puts("Hello world!")
});
Executes the specified function every "delay" seconds.
If "repeats" is specified, the function will only be called "repeats" times.
Next frame timer
NextFrame(() =>
{
Puts("Hello world!");
});
Executes the specified function at the next frame.
Web Requests
Web requests allow you to send a HTTP GET or POST to a specified URL.
The request will return true if the web request was sent, false if not. The callback is called with 2 parameters - an integer HTTP response code and a string response.
Basic Get method
using Oxide.Core.Libraries.Covalence;
namespace Oxide.Plugins
{
[Info("EpicStuff", "Unknown", 1.0)]
[Description("This example illustrates how to use a GET WebRequest")]
class EpicStuff : CovalencePlugin
{
[Command("get")]
void GetRequest(IPlayer player, string command, string[] args)
{
webrequest.EnqueueGet("http://www.google.com/search?q=oxide", (code, response) => GetCallback(code, response, player), this);
}
void GetCallback(int code, string response, IPlayer player)
{
if (response == null || code != 200)
{
Puts($"Error: {code} - Couldn't get an answer from Google for {player.Name}");
return;
}
Puts($"Google answered for {player.Name}: {response}");
}
}
}
This uses the raw connection to a web page as you would on your browser.
Basic POST method
using Oxide.Core.Libraries.Covalence;
namespace Oxide.Plugins
{
[Info("EpicStuff", "Unknown", 1.0)]
[Description("This example illustrates how to use a POST WebRequest")]
class EpicStuff : CovalencePlugin
{
[Command("post")]
void PostRequest(IPlayer player, string command, string[] args)
{
webrequest.EnqueuePost("http://www.google.com/search?q=oxide", "param1=value1¶m2=value2", (code, response) => PostCallback(code, response, player), this);
}
void PostCallback(int code, string response, IPlayer player)
{
if (response == null || code != 200)
{
Puts($"Error: {code} - Couldn't get an answer from Google for {player.Name}");
return;
}
Puts("Google answered for " + player.Name + ": " + response);
}
}
}
Advanced GET method
using Oxide.Core.Libraries.Covalence;
namespace Oxide.Plugins
{
[Info("EpicStuff", "Unknown", 1.0)]
[Description("This example illustrates how to use a GET WebRequest")]
class EpicStuff : CovalencePlugin
{
[Command("get")]
void GetRequest(IPlayer player, string command, string[] args)
{
// Set a custom timeout (in milliseconds)
var timeout = 200f;
// Set some custom request headers (eg. for HTTP Basic Auth)
var headers = new Dictionary<string, string> { { "header", "value" } };
webrequest.EnqueueGet("http://www.google.com/search?q=oxide", (code, response) => GetCallback(code, response, player), this, headers, timeout);
}
void GetCallback(int code, string response, IPlayer player)
{
if (response == null || code != 200)
{
Puts($"Error: {code} - Couldn't get an answer from Google for {player.Name}");
return;
}
Puts($"Google answered for {player.Name}: {response}");
}
}
}
Advanced POST method
using Oxide.Core.Libraries.Covalence;
namespace Oxide.Plugins
{
[Info("EpicStuff", "Unknown", 1.0)]
[Description("This example illustrates how to use a POST WebRequest")]
class EpicStuff : CovalencePlugin
{
[Command("post")]
void PostRequest(IPlayer player, string command, string[] args)
{
// Set a timeout (in milliseconds)
var timeout = 200f;
// Set some custom request headers (eg. for HTTP Basic Auth)
var headers = new Dictionary<string, string> { { "header", "value" } };
webrequest.EnqueuePost("http://www.google.com/search?q=oxide", "param1=value1¶m2=value2", (code, response) => PostCallback(code, response, player), this, headers, timeout);
}
void PostCallback(int code, string response, IPlayer player)
{
if (response == null || code != 200)
{
Puts($"Error: {code} - Couldn't get an answer from Google for {player.Name}");
return;
}
Puts("Google answered for " + player.Name + ": " + response);
}
}
}
Plugin Calling
Oxide allows you to expose methods in your plugin and make them available to other plugins. This allows you to access objects or properties from other plugins without having to replicate functionality yourself.
Exposing a plugin's method
namespace Oxide.Plugins
{
[Info("EpicStuff", "Unknown", 0.1)]
[Description("Makes epic stuff happen")]
class EpicStuff : CovalencePlugin
{
// Plugin methods can be a simple bool that is returned
bool GetReturn()
{
return true;
}
// Plugin methods can take parameters and return simple types
string TakeParam(string param, int secondParam)
{
if (param == "first parameter") return param;
else return "First parameter didn't match!";
}
// To return complex types, they should first be converted
// into builtin types (e.g. JSON.net types like JObject, JArray, etc. or builtin
// collections like System.Collections.Generic.Dictionary)
JObject ReturnObject()
{
var myObject = new JObject();
myObject["key"] = "value";
myObject["array"] = new JArray();
return myObject;
}
// Plugin methods don't have to return something
void SendMessage()
{
Puts("You just called the 'SendMessage' method!");
}
}
}
Exposing a plugin's method allows other plugins to call that method.
For example, you could write a plugin that does some player management, then allow other plugins to "query" it to get a list of players who have certain privileges set in the original plugin.
Calling a plugin's method
namespace Oxide.Plugins
{
[Info("SecondEpicStuff", "Unknown", 0.1)]
[Description("Makes more epic stuff happen")]
class SecondEpicStuff : CovalencePlugin
{
// First, add a reference to the plugin you are trying to call
// The name of this field needs to be the exact name of the desired plugin
// eg. We are referencing the example plugin above which is called 'EpicStuff'
[PluginReference]
Plugin EpicStuff;
// It's a good idea to check if the plugin you're trying to call
// has been loaded by oxide (otherwise you can't call the method)
void OnServerInitialized()
{
// Note: Trying to do this check in the plugin Init() method may
// fail, as the plugin load order may be different each time
if (EpicStuff == null)
{
PrintWarning("Plugin 'EpicStuff' was not found!");
}
}
void CallPlugin()
{
// Plugin methods return objects, so cast the API call to the type
// you're expecting
var getTypedReturn = (bool)EpicStuff?.Call("GetReturn");
// Send parameters through as variables after the method name
var takeParam = (string)EpicStuff?.Call("TakeParam", "param1", 1024);
// Use JSON.net to process the returned object
var returnedObject = EpicStuff?.Call("ReturnObject");
// Call a plugin to do some work without returning anything
EpicStuff?.Call("SendMessage");
}
}
}
Calling a plugin's method allows you to access results from another plugin.