Home / Edit Console Command Auto-completion

Console Command Auto-completion

<cat>Dev.Game</cat>
# 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`][Register Command] 
can be supplied with an auto-completion function.

```Lua
concommand.Add('my-command',onCommand,onAutoComplete)
```

This function can return an array of suggestions.

```Lua
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.

```Lua
function onAutoComplete ( command , parameters )
```

`command` : [String]

Name of the command that called the auto-completion function.

`parameters` : [String]

Anything written behind the commands itself.

<note>

	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.

</note>

<note>

	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.

</note>

 

#### Input Examples

![Input Basic]

```Markdown
command : `my-command`
parameters : ` `
```

![Input Extended]

```Markdown
command : `my-command` 
parameters : ` is useful`
```

 

#### Use Cases

The `command` parameter can be used to substitude the commands name.

```Lua
local function onAutoComplete ( command )
	return {
		command .. ' ' .. 'option'
	}
end
```

The `parameters` string can be process & used for nested suggestions.

```Lua
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.

```Lua
-- 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 <page>Global.AddCSLuaFile</page>, 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.


[MyCommand OptionA&B]: https://files.facepunch.com/wiki/files/b5604/8dc50ee732dcd4b.png
[Register Command]: /gmod/concommand.Add

[Input Extended]: https://files.facepunch.com/wiki/files/b5604/8dc50f193f3e756.png
[Input Basic]: https://files.facepunch.com/wiki/files/b5604/8dc50f17fc22663.png

[Parameters None]: https://files.facepunch.com/wiki/files/b5604/8dc50f9dbd184a4.png
[Parameters Was]: https://files.facepunch.com/wiki/files/b5604/8dc50f9f4a47a0e.png
[Parameters Is]: https://files.facepunch.com/wiki/files/b5604/8dc50f9fe248845.png

[Names Command]: https://files.facepunch.com/wiki/files/b5604/8dc5103cec1b54a.png
[Names Bots]: https://files.facepunch.com/wiki/files/b5604/8dc5104416b723d.png

[String]: /gmod/string

Garry's Mod Wiki

Player Guides

Getting Started 13

Sandbox Tools 3

Game Modes 4

Server Hosting 9

Console Command Auto-completion

Account Management

Special Pages

Wiki List

Garry's Mod Wiki