Console command system

Defining a command

The console and chat command system in Shine was made to make defining commands very easy. Instead of parsing the command string in each individual function you make, you just tell the command system what you want to get from each command argument and Shine will pass them along for you.

First of all, you need to make a function that you want to run whenever the command is issued. For server side commands, the first argument passed to a command's function is the client running it. For client commands, only your defined arguments are passed to it.

Registering the command

Once you have your function, register it as a Shine command with Plugin:BindCommand().

function Plugin:CreateCommands()
    local CommandObj = self:BindCommand( CommandName, ChatCommand, Function, AllowEveryone, ForceSilent )
end

First argument should be the console command you want to bind to this function. The second argument should be a single string or a table of strings which, when typed into chat as a command, will trigger this function. The third argument is the function to run.

The last two arguments are optional. Setting AllowEveryone to true will mean anyone can run the command regardless of permissions. Setting ForceSilent to true will force anyone using it through the chat to have their message hidden, i.e typing !example ^ Bleh with ForceSilent set would never show anyone that they typed that into chat.

Assigning parameters

Once your command is registered, you need to tell Shine what parameters to expect from the command. So if you want a command that takes client then string, you need to add two paramaters to the command of type "client" and "string".

To add a parameter, use CommandObj:AddParam().

CommandObj:AddParam{ Type = TypeName, ... }

Valid types are:

• "boolean"
• "client"
• "clients"
• "number"
• "string"
• "team"

All types can have a custom error message if not set to optional. This is done by adding an Error = ErrorString into the parameter table. You can set a parameter to optional with Optional = true. You can then set a default value or a function that returns the default value with Default = Value.

Numbers can have a minimum Min = Value, maximum Max = Value and be set to round off Round = true. Strings can be set to take from the entire line as one string TakeRestOfLine = true and have a max length MaxLength = Value.

Help text

You can also specify the text that should show when the command is listed using "sh_help".

CommandObj:Help( HelpText )

Here HelpText should be a short description of what the command does and the arguments it expects.

Client commands

Shine also supports creating commands on the client, but the argument types are more limited. Creating client commands must be done on the client side, in client.lua or shared.lua.

--Creating a standalone client command
local CommandObj = Shine:RegisterClientCommand( CommandName, Function )
CommandObj:AddParam{ Type = TypeName, ... }

--Creating a command for a plugin client side
function Plugin:CreateCommands()
    local CommandObj = self:BindCommand( CommandName, Function )
    CommandObj:AddParam{ Type = TypeName, ... }
end

--Deleting a standalone client command
Shine:RemoveClientCommand( CommandName )

Note that client commands only work through the console and have no permissions, so anyone can run them. The supported argument types on the client are string, number and boolean.

Examples

Print to another player's console.

This command will print a string into another player's console. It has the form:

sh_print Bob I'm in your console, printing stuff.

Bob's console: I'm in your console, printing stuff.

local function PrintToSomeone( Client, TargetClient, String )
    Shine:AdminPrint( TargetClient, String )
end
local Example = Shine:RegisterCommand( "sh_print", "print", PrintToSomeone )
Example:AddParam{ Type = "client" }
Example:AddParam{ Type = "string", Optional = true, TakeRestOfLine = true, Default = "Hello there!", MaxLength = 100 }

Print the square root of a number

This command will print the square root of whatever number you give it. It will not accept numbers less than 0, inputting a negative number will clamp it up to 0.

sh_number 100

Output: 10

local function NumberExample( Client, Number )
    Shine:AdminPrint( Client, tostring( math.sqrt( Number ) ) )
end
local Example = Shine:RegisterCommand( "sh_number", { "number", "squareroot" }, NumberExample )
Example:AddParam{ Type = "number", Min = 0, Error = "Please specify a number to square root." }

Send a PM to multiple people at once

This command will display a message to the given client's chat box from you.

sh_sayto bob,joe,@spectate I appear to be privately messaging you.

Bob's, joe's and all the spectator's chat: (PM) YourName: I appear to be privately messaging you.

local function NotifyPeople( Client, Targets, String )
    local Player = Client:GetControllingPlayer()
    local PlayerName = Player and Player:GetName() or "Console"
    Shine:Notify( Targets, "PM", PlayerName, String )
end
local Example = Shine:RegisterCommand( "sh_sayto", "sayto", NotifyPeople )
Example:AddParam{ Type = "clients" }
Example:AddParam{ Type = "string", TakeRestOfLine = true, MaxLength = kMaxChatLength }