Registry

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

Types

# `TypeDefinition`

interface TypeDefinition {

DisplayName: stringOptionally overrides the user-facing name of this type in the autocomplete menu. If omitted, the registered name of this type will be used.
Prefixes: stringString 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
) → TTransform 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) → anyParse 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) → stringThe 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.

}

# `CommandArgument`

interface CommandArgument {

Type: string  | TypeDefinitionThe argument type (case sensitive), or an inline TypeDefinition object
Name: stringThe argument name, this is displayed to the user as they type.
Description: stringA 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: stringThe 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: stringA 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
) → anyIf 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`

← Dispatcher Util →

Registry

Types

# TypeDefinition

# CommandArgument

# CommandDefinition

Properties

# Cmdr

Instance Methods

# RegisterTypesIn server only

Parameters

Returns

# RegisterType

Parameters

Returns

# RegisterTypePrefix

Parameters

Returns

# RegisterTypeAlias

Parameters

Returns

# GetType

Parameters

Returns

# GetTypeName

Parameters

Returns

# RegisterHooksIn server only

Parameters

Returns

# RegisterCommandsIn server only

Parameters

Parameters

Returns

Returns

# RegisterCommand server only

Parameters

Parameters

Returns

Returns

# RegisterDefaultCommands server only

Parameters

Returns

# GetCommand

Parameters

Returns

# GetCommands

Returns

# GetCommandNames

Returns

# RegisterHook

Parameters

Parameters

Returns

Returns

# GetStore

Parameters

Returns

# `TypeDefinition`

# `CommandArgument`

# `CommandDefinition`

# `Cmdr`

# `RegisterTypesIn` server only

# `RegisterType`

# `RegisterTypePrefix`

# `RegisterTypeAlias`

# `GetType`

# `GetTypeName`

# `RegisterHooksIn` server only

# `RegisterCommandsIn` server only

# `RegisterCommand` server only

# `RegisterDefaultCommands` server only

# `GetCommand`

# `GetCommands`

# `GetCommandNames`

# `RegisterHook`

# `GetStore`