Custom Commands

note

Kohl's Admin is currently in development. Everything in these docs is subject to change.

Custom commands are a core part of what makes Kohl's Admin as versatile as it is. This section will guide you through creation of your first custom commands!

Prerequisites

Make sure you have the Kohl's Admin script in your experience. Ensure that the script has a child folder named "Addons". By default this folder will contain some example addons.

Addon Setup

All custom commands are part of an Addon. For this section we will create addons that only create custom commands, but in later parts we will show the extent of what addons can do.

All addons are module scripts that return a function. To start, create a module script and inside of it write the following:

return function(_K)
    -- Addon code goes here!
end

Inside of this function is where we will be adding our custom commands. The name of the addon can be anything, but for this example we encourage "customCommands".

danger

Appending "Client" or "Server" to the end of an addon file's name will make it only run in that context. This will make the other context unaware of the command!

Creating a Custom Command

To create a custom command, you must register it with the Registry, using registerCommand().

Using this, our module becomes:

return function(_K)
    _K.Registry.registerCommand(_K, commandDefinition)
end

commandDefinition is a placeholder for the real contents of our command! Commands require a lot of information, structured in a commandDefinition.

type commandDefinition {
name: string, -- Name of the command.
aliases: { string }?, -- Table of aliases.
description: string, -- Description of what the command does.
group: string, -- What group the command belongs to.
args: { ArgumentDefinition }, -- A table of argument definitions.
envClient: {} | () -> {}?, -- Sets up an environment for the command.
env: {} | () -> {}?, -- Sets up an environment for the command.
runClient: (...any) -> ()?, -- What runs on the client of the player that ran the command.
run: (...any) -> ()? -- What the command runs on the server.
}

To give an example, this is the code from the ExampleAddon:

return function(_K)
  print("Hello World from ExampleAddon! IsServer:", _K.IsServer)

  _K.Registry.registerCommand(_K, {
   name = "customcommand",
   aliases = { "customcommandalias" },
   description = "Custom command description.",
   group = "General", -- Command group to use.
   args = {
    {
     type = "stringGreedy",
     name = "Message",
     description = "The message to send.", -- Description shown in command listings.
    },
   },
   runClient = function(context, message) -- Function that runs on executing player's client.
    print("Custom command ran on the client!", context, message)
   end,
   run = function(context, message) -- Function that runs on the server.
    print("Custom command ran on server!", context, message)
    local msgObject = Instance.new("Message")
    msgObject.Text = message
    msgObject.Parent = workspace
    task.delay(5, function()
     msgObject:Destroy()
    end)
   end,
  })
end

This command creates a Message instance and populates it with the player provided message. As you can see, the command is registered with a dictionary that lists all information about the command.

tip

You can put multiple custom commands in one addon! All you need to do is register multiple commands in the same module.

In later sections, we'll cover more advanced uses of custom commands, including environments and other advanced functionality.