-
Notifications
You must be signed in to change notification settings - Fork 37
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:
string
bool
int
float
double
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}";
}
}
If there is something missing or ambiguous, please create an issue or contact us on the Subnautica Modding Discord using our tags:
- PrimeSonic:
@PrimeSonic#0667
- Metious:
@Metious#3682
Please note that some pages are under construction and the links to them will be enabled as they are completed
[Adding]
- Items/GameObjects using Asset Classes
- Asynchronous loading for ModPrefab
- [Custom Scanner Unlocks]
- Items/GameObjects to the Spawning System
- [Recipes to uncraftable items]
- [Custom Mouse Click Actions]
[Editing]
- Background Type
- Crafting Time
- Equipment Type
- Quick Slot Type
- Size in Inventory
- [Recipes for craftable items]
- Harvest Settings
- BioReactor Fuel Values
- [Scanning Count/Time]
- [Spawning (Where/How often/How many)]
[General Utilities]
- In-Game Options Menu
- Adding crafting recipes for other mods items
- Using items from other mods
- Texture/Sprite Utilities
- [Adding/Playing Audio]
- Config Files using Abstract Json Config class
- Custom Console Commands
- [Registering OnSave/OnQuit Actions]
[Language]