Registry

The registry handles registering commands, types, and hooks. Exists on both client and server.

Types

TypeDefinition

interface TypeDefinition {

DisplayName: string

Optionally overrides the user-facing name of this type in the autocomplete menu. If omitted, the registered name of this type will be used.

Prefixes: string

String containing default Prefixed Union Types for this type. This property should omit the initial type name, so this string should begin with a prefix character, e.g. Prefixes = "# integer ! boolean".

Transform: nil | function(

rawText: string,
executor: Player

) → T

Transform is an optional function that is passed two values: the raw text, and the player running the command. Then, whatever values this function returns will be passed to all other functions in the type (Validate, Autocomplete, and Parse).

Validate: nil | function(value: T) → boolean, string?

The Validate function is passed whatever is returned from the Transform function (or the raw value if there is no Transform function). If the value is valid for the type, it should return true. If it the value is invalid, it should return two values: false, and a string containing an error message.

If this function isn't present, anything will be considered valid.

ValidateOnce: nil | function(value: T) → boolean, string?

This function works exactly the same as the normal Validate function, except it only runs once (after the user presses Enter). This should only be used if the validation process is relatively expensive or needs to yield. For example, the PlayerId type uses this because it needs to call GetUserIdFromNameAsync in order to validate.

For the vast majority of types, you should just use Validate instead.

Autocomplete: nil | function(value: T) → array<string>, nil | {

IsPartial: boolean?

If true, pressing Tab to auto complete won't continue onwards to the next argument.

}

Should only be present for types that are possible to be auto completed. It should return an array of strings that will be displayed in the auto complete menu. It can also return a second value, which can be a dictionary with options such as IsPartial as described above.

Parse: function(value: T) → any

Parse is the only required function in a type definition. It is the final step before the value is considered finalized. This function should return the actual parsed value that will be sent to the command functions.

Default: nil | function(player: Player) → string

The Default function is optional and should return the "default" value for this type, as a string. For example, the default value of the players type is the name of the player who ran the command.

Listable: boolean?

If you set the optional key Listable to true in your table, this will tell Cmdr that comma-separated lists are allowed for this type. Cmdr will automatically split the list and parse each segment through your Transform, Validate, Autocomplete, and Parse functions individually, so you don't have to change the logic of your Type at all.

The only limitation is that your Parse function must return a table. The tables from each individual segment's Parse will be merged into one table at the end of the parse step. The uniqueness of values is ensured upon merging, so even if the user lists the same value several times, it will only appear once in the final table.

ArgumentOperatorAliases: {[string]: string}

Table containing a map from an alias to the equivalent argument value operator (., *, ?, etc.) This is used for aliases like "all", "others", "me" for specific types.

}

CommandArgument

interface CommandArgument {

Type: string | TypeDefinition

The argument type (case sensitive), or an inline TypeDefinition object

Name: string

The argument name, this is displayed to the user as they type.

Description: string

A description of what the argument is, this is also displayed to the user.

Optional: boolean?

If this is present and set to true, then the user can run the command without filling out this value. The argument will be sent to your commands as nil.

Default: any?

If present, the argument will be optional and if the user doesn't supply a value, your function will receive whatever you set this to. Default being set implies Optional = true, so Optional can be omitted.

}

CommandDefinition

interface CommandDefinition {

Name: string

The name that's in auto complete and displayed to user.

Aliases: array<string>

Aliases that are not in the autocomplete, but if matched will run this command just the same. For example, m might be an alias of announce.

Description: string

A description of the command which is displayed to the user.

Group: any?

Optional, can be be any value you wish. This property is intended to be used in hooks, so that you can categorize commands and decide if you want a specific user to be able to run them or not.

Args: array<CommandArgument | function(context) → CommandArgument>

Array of CommandArgument objects, or functions that return CommandArgument objects.

Data: nil | function(

context: CommandContext,
...: any

) → any

If your command needs to gather some extra data from the client that's only available on the client, then you can define this function. It should accept the CommandContext for the current command as an argument, and return a single value which will be available in the command with CommandContext.GetData.

ClientRun: nil | function(

context: CommandContext,
...: any

) → string?

If you want your command to run on the client, you can add this function to the command definition itself. It works exactly like the function that you would return from the Server module.

• If this function returns a string, the command will run entirely on the client and won't touch the server (which means server-only hooks won't run).
• If this function doesn't return anything, it will fall back to executing the Server module on the server.

WARNING

If this function is present and there isn't a Server module for this command, it is considered an error to not return a string from this function.

AutoExec: array<string>

A list of commands to run automatically when this command is registered at the start of the game. This should primarily be used to register any aliases regarding this command with the built-in alias command, but can be used for initializing state as well. Command execution will be deferred until the end of the frame.

}

Properties

Cmdr

Registry.Cmdr: Cmdr | CmdrClient

A reference to Cmdr. This may either be the server or client version of Cmdr depending on where the code is running.

Instance Methods

RegisterTypesIn server only

Registry.RegisterTypesIn(container: Instance) →

Registers all types from within a container.

Parameters

Name	Type	Required
container	Instance	✔

Returns

Type

RegisterType

Registry.RegisterType(

name: string,
typeDefinition: TypeDefinition

) →

Registers a type. This function should be called from within the type definition ModuleScript.

Parameters

Name	Type	Required
name	string	✔
typeDefinition	TypeDefinition	✔

Returns

Type

v1.3.0+

RegisterTypePrefix

Registry.RegisterTypePrefix(

name: string,
union: string

) →

Registers a Prefixed Union Type string for the given type. If there are already type prefixes for the given type name, they will be concatenated. This allows you to contribute prefixes for default types, like players.

Parameters

Name	Type	Required
name	string	✔
union	string	✔	The string should omit the initial type name, so this string should begin with a prefix character, e.g. "# integer ! boolean".

Returns

Type

v1.3.0+

RegisterTypeAlias

Registry.RegisterTypeAlias(

name: string,
union: string

) →

Allows you to register a name which will be expanded into a longer type which will can be used as command argument types. For example, if you register the alias "stringOrNumber" it could be interpreted as "string # number" when used.

Parameters

Name	Type	Required
name	string	✔
union	string	✔	The string should include the initial type name, e.g. "string # integer ! boolean".

Returns

Type

GetType

Registry.GetType(name: string) → TypeDefinition?

Returns a type definition with the given name, or nil if it doesn't exist.

Parameters

Name	Type	Required
name	string	✔

Returns

Type
TypeDefinition?

v1.3.0+

GetTypeName

Registry.GetTypeName(name: string) → string

Returns a type name taking aliases into account. If there is no alias, the name parameter is simply returned as a pass through.

Parameters

Name	Type	Required
name	string	✔

Returns

Type
string

RegisterHooksIn server only

Registry.RegisterHooksIn(container: Instance) →

Registers all hooks from within a container on both the server and the client. If you want to add a hook to the server or the client only (not on both), then you should use the Registry.RegisterHook method directly by requiring Cmdr in a server or client script.

Parameters

Name	Type	Required
container	Instance	✔

Returns

Type

RegisterCommandsIn server only

Registry.RegisterCommandsIn(

container: Instance,
filter?: function(command: CommandDefinition) → boolean

) →

Registers all commands from within a container.

Parameters

Name	Type	Required
container	Instance	✔
filter	function(command: CommandDefinition) → boolean Details Parameters Name Type Required command CommandDefinition ✔ Returns Type boolean	✘	If present, will be passed a command definition which will then only be registered if the function returns true.

Returns

Type

RegisterCommand server only

Registry.RegisterCommand(

commandScript: ModuleScript,
commandServerScript?: ModuleScript?,
filter?: function(command: CommandDefinition) → boolean

) →

Registers an individual command directly from a module script and possible server script. For most cases, you should use Registry.RegisterCommandsIn instead.

Parameters

Name	Type	Required
commandScript	ModuleScript	✔
commandServerScript	ModuleScript?	✘
filter	function(command: CommandDefinition) → boolean Details Parameters Name Type Required command CommandDefinition ✔ Returns Type boolean	✘	If present, will be passed a command definition which will then only be registered if the function returns true.

Returns

Type

RegisterDefaultCommands server only

1. Registry.RegisterDefaultCommands(groups: array<string>) →

2. Registry.RegisterDefaultCommands(groups: array<string>) →

3. Registry.RegisterDefaultCommands(groups: array<string>) →

4. Registry.RegisterDefaultCommands(groups: array<string>) →

5. Registry.RegisterDefaultCommands(groups: array<string>) →

6. Registry.RegisterDefaultCommands(groups: array<string>) →

7. Registry.RegisterDefaultCommands(filter: function(command: CommandDefinition) → boolean) →

Registers the default set of commands.

📚 Showing overload 1 of 7

Parameters

Name	Type	Required
groups	array<string>	✔	Limit registration to only commands which have their Group property set to thes.

Returns

Type

GetCommand

Registry.GetCommand(name: string) → CommandDefinition?

Returns the CommandDefinition of the given name, or nil if not registered. Command aliases are also accepted.

Parameters

Name	Type	Required
name	string	✔

Returns

Type
CommandDefinition?

GetCommands

Registry.GetCommands() → array<CommandDefinition>

Returns an array of all commands (aliases not included).

Returns

Type
array<CommandDefinition>

GetCommandNames

Registry.GetCommandNames() → array<string>

Returns an array of all command names.

Returns

Type
array<string>

RegisterHook

Registry.RegisterHook(

hookName: "BeforeRun" | "AfterRun",
callback: function(context: CommandContext) → string?,
priority?: number?

) →

Adds a hook. This should probably be run on the server, but can also work on the client. Hooks run in order of priority (lower number runs first).

Parameters

Name	Type	Required
hookName	"BeforeRun" | "AfterRun"	✔
callback	function(context: CommandContext) → string? Details Parameters Name Type Required context CommandContext ✔ Returns Type string?	✔
priority	number?	✘

Returns

Type

GetStore

Registry.GetStore(name: string) → table

Returns a table saved with the given name. This is the same as CommandContext.GetStore

Parameters

Name	Type	Required
name	string	✔

Returns

Type
table