Commands
In this section, we go over even more ways to set up commands. Including name aliases, overloads and optional parameters.
As mentioned before, the [Command]
attribute is used on any method or property, to register commands.
Adding static commands
The simplest way to add a command is with static methods, as there is no additional steps required. Simply put the [Command]
attribute on the method, and you're all set!
[Command]
public static void SayHello()
{
Debug.Log("Hello world!");
}
By default, the method name is used for the command, unless other names have been specified.
If multiple names are assigned, they serve as aliases for the same command, overwriting the original method name.
[Command("Test", "Hello", "Debug")]
public static void SayHello()
{
Debug.Log("Hello world!");
}
Commands can also take parameters just like any regular method.
[Command]
public static int Multiply(int a, int b)
{
return a * b;
}
Returning a value in your method will automatically log it to the console.
Non-static commands
Non-static methods or properties require an instance in order to be executed. Instances are found automatically behind the scenes, which means there is no additional setup required on your part.
public class Player : MonoBehaviour
{
private float currentHealth;
[Command]
public int Health
{
get => currentHealth;
set => currentHealth = value;
}
}
Typing: health 10
will execute on all instances of Player
found in the scene.
Additionally, a name can be specified at the end of the input prefixed with @
. Doing so will execute the command only on instances with the specified name.
The name is always specified at the end of the last required parameter.
So for example, if we want to just print the value of a property instead of setting it, we could type: health @MyPlayer
.
Overloaded commands
Multiple commands can share the same name, provided that either the parameter types or number vary.
[Command]
public static void LoadScene(string name)
{
SceneManager.LoadScene(name);
}
[Command]
public static void LoadScene(int buildIndex)
{
SceneManager.LoadScene(buildIndex);
}
Based on the input when typing the argument, the command field will automatically select the first matching command.
int
parameters are prioritized higher than float
parameters. To differentiate between them, you can put a decimal on your float
values. The same principle applies to vectors.
Parameter types
All primitive types and basic Unity value types such as Vector3
and Color
are supported out of the box. Also, most types derived from UnityEngine.Object
can be used as parameters.
This means types like GameObject
, ScriptableObject
, MonoBehaviour
can be used as parameters without any setup.
When typing the parameter in the command field, we specify the name of the object we want to reference. The object is then found automatically with the given name.
It's also possible to use prefab game objects as parameters. To do this, we can place a [Prefab]
attribute in front of our parameter. Like so:
[Command]
public string SetPrefabTag([Prefab]GameObject prefab, string tag)
{
if (prefab != null)
prefab.tag = tag;
}
When making editor commands, asset types like MonoScript
, StyleSheet
, Shader
etc. can also be used as parameters. The assets are found by name, in the asset database.
Custom types are also supported as parameters. See the converters section for more details about custom types.
Optional parameters
[Command]
public void Damage(int amount = 1)
{
health -= amount;
}
Optional parameter values are also supported. You can simply define a method with default optional parameters.
Given the example above, if you were to execute the command without any argument, it would default to dealing 1 damage.
Additional attributes
- Description
- Prefix
- Editor Only
- Runtime Only
[Command]
[Description("Gives 5000 coins to the player")]
public static void Motherlode()
{
coins += 5000;
}
Commands can have a description added to them with the [Description]
attribute.
To see the description of a command, type help <command name>
in the command field.
[Prefix("score")]
public static class ScoreManager
{
[Command]
public static int Current { get; set; }
[Command]
public static void Reset()
{
Current = 0;
}
}
Commands can be organized together by using the [Prefix]
attribute on a class, which then groups all the commands in that class under the same prefix.
It can be used on classes, methods or properties.
The above example would result in the commands looking like this in the command field:
The prefix character can be changed in project settings. See the settings section for more details.
[Command]
[EditorOnly]
public static void RefreshAssets()
{
AssetDatabase.SaveAssets();
AssetDatabase.Refresh();
}
Commands can be constrained to only show up in edit-mode, and not be shown in play-mode, with the [EditorOnly]
attribute.
It can be used on classes, methods or properties.
[Command]
[RuntimeOnly]
public static void HealPlayers(int amount)
{
Player[] players = FindObjectsByType<Player>(FindObjectsSortMode.None);
foreach (var player in players)
{
player.Health += amount;
}
}
Commands can be constrained to only show up in play-mode, and not be shown in edit-mode, with the [RuntimeOnly]
attribute.
It can be used on classes, methods or properties.