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>

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.

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.

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

The argument type (case sensitive).

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>

Array of 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.

}

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>

# GetCommandsAsStrings

Registry.GetCommandsAsStrings() → 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
Last Updated: 11/15/2019, 11:58:45 AM