Console Command Auto-completion

Auto-Complete

Auto-complete suggests possible continuations for
commands users are typing into their console.

This mechanic not only simplifies using commands
but also teaches users how they can use them.

Completion Function

Commands registered with concommand.Add
can be supplied with an auto-completion function.

concommand.Add('my-command',onCommand,onAutoComplete)

This function can return an array of suggestions.

local function onAutoComplete () return { 'my-command OptionA' , 'my-command OptionB' } end

The suggestions will be displayed below the input.

MyCommand OptionA&B

Parameters

The completion function also receives 2 parameters that
allow you to return more context aware suggestions.

function onAutoComplete ( command , parameters )

command : String

Name of the command that called the auto-completion function.

parameters : String

Anything written behind the commands itself.

As command names aren't case-sensitive, the command parameter can have any
case ( mY-CoMMaND ) and should be normalized when used with lookup tables.

The auto-completion function is only called if at least 1 character has been written after
the command's name, as such parameters will always start with a space character.

Input Examples

Input Basic

command : `my-command` parameters : ` `

Input Extended

command : `my-command` parameters : ` is useful`

Use Cases

The command parameter can be used to substitude the commands name.

local function onAutoComplete ( command ) return { command .. ' ' .. 'option' } end

The parameters string can be process & used for nested suggestions.

local function onAutoComplete ( command , parameters ) -- Normalizes the string parameters = parameters:Trim():lower() -- Splits the string into an array parameters = string.Explode('%s+',parameters,true) if parameters[ 1 ] == 'is' then return { command .. ' is useful' } end if parameters[ 1 ] == 'was' then return { command .. ' was broken' } end return { command .. ' ' .. 'was' , command .. ' ' .. 'is' } end

Only typing the command suggests two possible sub-commands.

Parameters None

Adding the was sub-command displays only options specific to it.

Parameters Was

Adding the is sub-command displays only options specific to it.

Parameters Is

Examples

Bot Name List

Suggests bot player names based on the current input.

-- Finds all bot names that match the current input local function matchingBotNames ( input ) local names = {} local bots = player.GetBots() for _ , bot in ipairs(bots) do local name = bot:Nick() if name:lower():find(input) then table.insert(names,name) end end return names end local function onAutoComplete ( command , input ) -- Normalizes the string input = input:Trim():lower() -- Wrap the bot names as suggestions local suggestions = {} local names = matchingBotNames(input) for _ , name in ipairs(names) do local suggestion = command .. ' "' .. name .. '"' table.insert(suggestions,suggestion) end return suggestions end local function onCommand () end concommand.Add( 'bot-command' , onCommand , onAutoComplete )

Spawn some bot players with the bot command.

Names Bots

Their names will be suggested as follows.

Names Command

Console command replication

Console commands are not replicated. If you'd like to replicate a console command, you'll have to use AddCSLuaFile, or create custom behavior on both the server & the client.

Special thanks to old-time contributors for the images. The code was written by shawnjbragdon.