Custom Console Commands
SMLHelper provides a simple API for allowing you to define custom console commands for your mod to respond to when the user types them into the in-game dev console, with simple parameter type checking to enable user- and developer-friendly error reporting, both on-screen and in the log.
Currently, only the following types are supported by the API:
stringboolintfloatdouble
If you wish to use a type not in this list, it is recommended to use string (as that is what the value coming from the user will be anyway) and handle converting and error-checking the value for yourself.
There are three ways to register custom console commands, so you can use whichever suits your purpose or coding-style best.
By calling ConsoleCommandsHandler.Main.RegisterConsoleCommand<T>(string command, T callback), you can pass an instance of the delegate, whether it is an anonymous lambda or reference to a method that implements the delegate signature to register your callback as a response to the command.
Note that with a delegate command, it is not possible to use optional parameters. If you want optional parameters, it is recommended to register a public static method as a command instead.
using QModManager.API.ModLoading;
using SMLHelper.V2.Handlers;
[QModCore]
public static class MyMod
{
[QModPatch]
public static void Patch()
{
/// Here we are registering a console command by use of a delegate. The delegate will respond to the "delegatecommand"
/// command from the dev console, passing values following "delegatecommand" as the correct types, provided they can be
/// parsed to that type. For example, "delegatecommand foo 3 true" would be a valid command for the
/// MyCommand delegate signature. You can also use Func or Action to define your delegate signatures if you prefer,
/// and you can also pass a reference to a method that matches this signature.
///
/// Registered commands must be unique. If any mod has already added the command, your command will be rejected.
///
/// If the user enters incorrect parameters for a command, they will be notified of the expected parameter types,
/// both on-screen and in the log.
///
/// Note that a command can have a return type, but it is not necessary. If it does return any type, it will be printed
/// both on-screen and in the log.
ConsoleCommandsHandler.Main.RegisterConsoleCommand<MyCommand>("delegatecommand", (myString, myInt, myBool) =>
{
return $"Parameters: {myString} {myInt} {myBool}";
});
Logger.Log(Logger.Level.Info, "Patched successfully!");
}
private delegate string MyCommand(string myString, int myInt, bool myBool);
}By calling ConsoleCommandsHandler.Main.RegisterConsoleCommand(string command, Type declaringType, string methodName, Type[] parameters = null), you can specify a public static method as a response to the command. The API here is similar to Harmony in that it will search for the method in the given type, using the optional Type[] parameters to target overloads.
using QModManager.API.ModLoading;
using SMLHelper.V2.Handlers;
[QModCore]
public static class MyMod
{
[QModPatch]
public static void Patch()
{
/// Here we are registering a console command by specifying a target method. The method will respond to the "methodcommand"
/// command from the dev console, passing values following "methodcommand" as the correct types, provided they can be
/// parsed to that type. For example, "methodcommand foo 3 true" would be a valid command for the MyCommand method
/// signature.
///
/// Registered commands must be unique. If any mod has already added the command, your command will be rejected.
///
/// If the user enters incorrect parameters for a command, they will be notified of the expected parameter types,
/// both on-screen and in the log.
///
/// Note that a command can have a return type, but it is not necessary. If it does return any type, it will be printed
/// both on-screen and in the log.
ConsoleCommandsHandler.Main.RegisterConsoleCommand("methodcommand", typeof(MyMod), nameof(MyCommand));
Logger.Log(Logger.Level.Info, "Patched successfully!");
}
public static string MyCommand(string myString, int myInt, bool myBool = false)
{
return $"Parameters: {myString} {myInt} {myBool}";
}
}By calling ConsoleCommandsHandler.Main.RegisterConsoleCommands(Type type), you can register all public static methods decorated with the ConsoleCommandAttribute as console commands.
using QModManager.API.ModLoading;
using SMLHelper.V2.Commands;
using SMLHelper.V2.Handlers;
[QModCore]
public static class MyMod
{
[QModPatch]
public static void Patch()
{
/// Here we are registering all console commands specified in the MyConsoleCommands type as console commands.
/// Methods decorated with the ConsoleCommandAttribute will respond to the the relevant
/// command from the dev console.
///
/// Registered commands must be unique. If any mod has already added the command, your command will be rejected.
///
/// If the user enters incorrect parameters for a command, they will be notified of the expected parameter types,
/// both on-screen and in the log.
///
/// Note that a command can have a return type, but it is not necessary. If it does return any type, it will be printed
/// both on-screen and in the log.
ConsoleCommandsHandler.Main.RegisterConsoleCommands(typeof(MyConsoleCommands));
Logger.Log(Logger.Level.Info, "Patched successfully!");
}
}
public static class MyConsoleCommands
{
/// The MyAttributedCommand method will respond to the "attributedcommand" command from the dev console.
[ConsoleCommand("attributedcommand")]
public static string MyAttributedCommand(string myString, int myInt, bool myBool = false)
{
return $"Parameters: {myString} {myInt} {myBool}";
}
}