Settings

⚠️ Warning

This wiki has been replaced by the wiki on our website. This wiki will be removed in the future.

Settings

A list of all settings that can be used to customize how the language server operates.

❗Important

All of these settings should be prefixed with Lua. e.g. Lua.completion.enable or Lua.diagnostics.globals when editing a configuration file - except when using a .luarc.json file.

When using a .luarc.json file, the prefix is not needed and the settings can be entered as they appear on this page.

addonManager

Settings that affect the VS Code addon manager

addonManager.enable

Type: boolean

Default: true

Set the on/off state of the addon manager. Disabling the addon manager prevents it from registering its command.

completion

Settings that adjust how autocompletions are provided while typing.

completion.autoRequire

Type: boolean

Default: true

When the input looks like a file name, automatically require the file.

completion.callSnippet

Type: string

Default: "Disable"

Options:

• "Disable" - Only show function name
• "Both" - Show function name and snippet
• "Replace" - Only show the call snippet

Whether to show call snippets or not. When disabled, only the function name will be completed. When enabled, a "more complete" snippet will be offered.

ℹ️ Note: the below GIF is using the "Both" option

completion.displayContext

Type: integer

Default: 0 (disabled)

When a snippet is being suggested, this setting will set the amount of lines around the snippet to preview to help you better understand its usage.

Setting to 0 will disable this feature.

completion.enable

Type: boolean

Default: true

Enable/disable completion. Completion works like any autocompletion you already know of. It helps you type less and get more done.

completion.keywordSnippet

Type: string

Default: "Replace"

Options:

• "Disable" - Only completes the keyword
• "Both" - Offers a completion for the keyword and snippet
• "Replace" - Only shows a snippet

Whether to show a snippet for key words like if, while, etc. When disabled, only the keyword will be completed. When enabled, a "more complete" snippet will be offered.

completion.postfix

Type: string

Default: @

The character to use for triggering a "postfix suggestion". A postfix allows you to write some code and then trigger a snippet after (post) to "fix" the code you have written. This can save some time as instead of typing table.insert(myTable, ), you can just type myTable@.

completion.requireSeparator

Type: string

Default: .

The separator to use when require-ing a file.

completion.showParams

Type: boolean

Default: true

Display a function's parameters in the list of completions. When a function has multiple definitions, they will be displayed separately.

completion.showWord

Type: string

Default: "Fallback"

Options:

• "Enable" - Always show contextual words in completion suggestions
• "Fallback" - Only show contextual words when smart suggestions based on semantics cannot be provided
• "Disable" - Never show contextual words

Show "contextual words" that have to do with Lua but are not suggested based on their usefulness in the current semantic context.

completion.workspaceWord

Type: boolean

Default: true

Whether words from other files in the workspace should be suggested as "contextual words". This can be useful for completing similar strings. completion.showWord must not be disabled for this to have an effect.

diagnostics

Settings to adjust the diagnostics for Info, Warning, and Error

diagnostics.disable

Type: Array<diagnostic_name>

Default: []

Disable certain diagnostics globally. For example, if you want all warnings for lowercase-global to be disabled, the value for diagnostics.disable would be ["lowercase-global"].

diagnostics.disableScheme

Type: Array<string>

Default: ["git"]

Disable diagnosis of Lua files that have the set schemes.

diagnostics.enable

Type: boolean

Default: true

Whether all diagnostics should be enabled or not.

diagnostics.globals

Type: Array<string>

Default: []

An array of variable names that will be declared as global.

diagnostics.groupFileStatus

Type: Object<diagnostic_group_name, file_state>

file_state Options:

• "Any" - Any loaded file (workspace, library, etc.) will use this diagnostic group
• "Opened" - Only opened files will use this diagnostic group
• "None" - This diagnostic group will be disabled
• "Fallback" - The diagnostics in this group are controlled individually by diagnostics.neededFileStatus

Default Value

{
    /*
    * ambiguity-1
    * count-down-loop
    * different-requires
    * newfield-call
    * newline-call
    */
    "ambiguity": "Fallback",
    /*
    * await-in-sync
    * not-yieldable
    */
    "await": "Fallback",
    /*
    * codestyle-check
    * spell-check
    */
    "codestyle": "Fallback",
    /*
    * duplicate-index
    * duplicate-set-field
    */
    "duplicate": "Fallback",
    /*
    * global-in-nil-env
    * lowercase-global
    * undefined-env-child
    * undefined-global
    */
    "global": "Fallback",
    /*
    * cast-type-mismatch
    * circle-doc-class
    * doc-field-no-class
    * duplicate-doc-alias
    * duplicate-doc-field
    * duplicate-doc-param
    * undefined-doc-class
    * undefined-doc-name
    * undefined-doc-param
    * unknown-cast-variable
    * unknown-diag-code
    * unknown-operator
    */
    "luadoc": "Fallback",
    /*
    * redefined-local
    */
    "redefined": "Fallback",
    /*
    * close-non-object
    * deprecated
    * discard-returns
    */
    "strict": "Fallback",
    /*
    * no-unknown
    */
    "strong": "Fallback",
    /*
    * assign-type-mismatch
    * cast-local-type
    * cast-type-mismatch
    * need-check-nil
    * param-type-mismatch
    * return-type-mismatch
    * undefined-field
    */
    "type-check": "Fallback",
    /*
    * missing-parameter
    * missing-return
    * missing-return-value
    * redundant-parameter
    * redundant-return-value
    * redundant-value
    * unbalanced-assignments
    */
    "unbalanced": "Fallback",
    /*
    * code-after-break
    * empty-block
    * redundant-return
    * trailing-space
    * unreachable-code
    * unused-function
    * unused-label
    * unused-local
    * unused-vararg
    */
    "unused": "Fallback"
}

Set the file status required for each diagnostic group. This setting is an Object of key-value pairs where the key is the name of the diagnostic group and the value is the state that a file must be in in order for the diagnostic group to apply.

diagnostics.groupSeverity

Type: Object<diagnostic_group_name, severity>

severity Options:

• "Error" - An error will be raised
• "Warning" - A warning will be raised
• "Information" - An information or note will be raised
• "Hint" - The affected code will be "hinted" at
• "Fallback" - The diagnostics in this group will be controlled individually by diagnostics.severity

Default Value

{
    /*
    * ambiguity-1
    * count-down-loop
    * different-requires
    * newfield-call
    * newline-call
    */
    "ambiguity": "Fallback",
    /*
    * await-in-sync
    * not-yieldable
    */
    "await": "Fallback",
    /*
    * codestyle-check
    * spell-check
    */
    "codestyle": "Fallback",
    /*
    * duplicate-index
    * duplicate-set-field
    */
    "duplicate": "Fallback",
    /*
    * global-in-nil-env
    * lowercase-global
    * undefined-env-child
    * undefined-global
    */
    "global": "Fallback",
    /*
    * cast-type-mismatch
    * circle-doc-class
    * doc-field-no-class
    * duplicate-doc-alias
    * duplicate-doc-field
    * duplicate-doc-param
    * undefined-doc-class
    * undefined-doc-name
    * undefined-doc-param
    * unknown-cast-variable
    * unknown-diag-code
    * unknown-operator
    */
    "luadoc": "Fallback",
    /*
    * redefined-local
    */
    "redefined": "Fallback",
    /*
    * close-non-object
    * deprecated
    * discard-returns
    */
    "strict": "Fallback",
    /*
    * no-unknown
    */
    "strong": "Fallback",
    /*
    * assign-type-mismatch
    * cast-local-type
    * cast-type-mismatch
    * need-check-nil
    * param-type-mismatch
    * return-type-mismatch
    * undefined-field
    */
    "type-check": "Fallback",
    /*
    * missing-parameter
    * missing-return
    * missing-return-value
    * redundant-parameter
    * redundant-return-value
    * redundant-value
    * unbalanced-assignments
    */
    "unbalanced": "Fallback",
    /*
    * code-after-break
    * empty-block
    * redundant-return
    * trailing-space
    * unreachable-code
    * unused-function
    * unused-label
    * unused-local
    * unused-vararg
    */
    "unused": "Fallback"
}

diagnostics.ignoredFiles

Type: string

Default: "Opened"

Options:

• "Enable" - Always diagnose ignored files... kind of defeats the purpose of ignoring them.
• "Opened" - Only diagnose ignored files when they are open
• "Disable" - Ignored files are fully ignored

Set how files that have been ignored should be diagnosed.

diagnostics.libraryFiles

Type: string

Default: "Opened"

Options:

• "Enable" - Always diagnose library files
• "Opened" - Only diagnose library files when they are open
• "Disable" - Never diagnose library files

Set how files loaded with workspace.library are diagnosed.

diagnostics.neededFileStatus

Type: Object<diagnostic_name, file_state>

file_state Options:

• "Any" - Any loaded file (workspace, library, etc.) will use this diagnostic group
• "Opened" - Only opened files will use this diagnostic group
• "None" - This diagnostic group will be disabled
• "Any!" - Like "Any" but overrides diagnostics.groupFileStatus
• "Opened!" - Like "Opened" but overrides diagnostics.groupFileStatus
• "None!" - Like "None" but overrides diagnostics.groupFileStatus

Default Value

{
    "ambiguity-1": "Any",
    "assign-type-mismatch": "Opened",
    "await-in-sync": "None",
    "cast-local-type": "Opened",
    "cast-type-mismatch": "Any",
    "circle-doc-class": "Any",
    "close-non-object": "Any",
    "code-after-break": "Opened",
    "codestyle-check": "None",
    "count-down-loop": "Any",
    "deprecated": "Any",
    "different-requires": "Any",
    "discard-returns": "Any",
    "doc-field-no-class": "Any",
    "duplicate-doc-alias": "Any",
    "duplicate-doc-field": "Any",
    "duplicate-doc-param": "Any",
    "duplicate-index": "Any",
    "duplicate-set-field": "Any",
    "empty-block": "Opened",
    "global-in-nil-env": "Any",
    "lowercase-global": "Any",
    "missing-parameter": "Any",
    "missing-return": "Any",
    "missing-return-value": "Any",
    "need-check-nil": "Opened",
    "newfield-call": "Any",
    "newline-call": "Any",
    "no-unknown": "None",
    "not-yieldable": "None",
    "param-type-mismatch": "Opened",
    "redefined-local": "Opened",
    "redundant-parameter": "Any",
    "redundant-return": "Opened",
    "redundant-return-value": "Any",
    "redundant-value": "Any",
    "return-type-mismatch": "Opened",
    "spell-check": "None",
    "trailing-space": "Opened",
    "unbalanced-assignments": "Any",
    "undefined-doc-class": "Any",
    "undefined-doc-name": "Any",
    "undefined-doc-param": "Any",
    "undefined-env-child": "Any",
    "undefined-field": "Opened",
    "undefined-global": "Any",
    "unknown-cast-variable": "Any",
    "unknown-diag-code": "Any",
    "unknown-operator": "Any",
    "unreachable-code": "Opened",
    "unused-function": "Opened",
    "unused-label": "Opened",
    "unused-local": "Opened",
    "unused-vararg": "Opened"
}

diagnostics.severity

Type: Object<diagnostic_name, severity>

severity Options:

• "Error" - An error will be raised
• "Warning" - A warning will be raised
• "Information" - An information or note will be raised
• "Hint" - The affected code will be "hinted" at
• "Error!" - Like "Error" but overrides diagnostics.groupSeverity
• "Warning!" -Like "Warning" but overrides diagnostics.groupSeverity
• "Information!" - Like "Information" but overrides diagnostics.groupSeverity
• "Hint!" - Like "Hint" but overrides diagnostics.groupSeverity

Default Value

{
    "ambiguity-1": "Warning",
    "assign-type-mismatch": "Warning",
    "await-in-sync": "Warning",
    "cast-local-type": "Warning",
    "cast-type-mismatch": "Warning",
    "circle-doc-class": "Warning",
    "close-non-object": "Warning",
    "code-after-break": "Hint",
    "codestyle-check": "Warning",
    "count-down-loop": "Warning",
    "deprecated": "Warning",
    "different-requires": "Warning",
    "discard-returns": "Warning",
    "doc-field-no-class": "Warning",
    "duplicate-doc-alias": "Warning",
    "duplicate-doc-field": "Warning",
    "duplicate-doc-param": "Warning",
    "duplicate-index": "Warning",
    "duplicate-set-field": "Warning",
    "empty-block": "Hint",
    "global-in-nil-env": "Warning",
    "lowercase-global": "Information",
    "missing-parameter": "Warning",
    "missing-return": "Warning",
    "missing-return-value": "Warning",
    "need-check-nil": "Warning",
    "newfield-call": "Warning",
    "newline-call": "Warning",
    "no-unknown": "Warning",
    "not-yieldable": "Warning",
    "param-type-mismatch": "Warning",
    "redefined-local": "Hint",
    "redundant-parameter": "Warning",
    "redundant-return": "Hint",
    "redundant-return-value": "Warning",
    "redundant-value": "Warning",
    "return-type-mismatch": "Warning",
    "spell-check": "Information",
    "trailing-space": "Hint",
    "unbalanced-assignments": "Warning",
    "undefined-doc-class": "Warning",
    "undefined-doc-name": "Warning",
    "undefined-doc-param": "Warning",
    "undefined-env-child": "Information",
    "undefined-field": "Warning",
    "undefined-global": "Warning",
    "unknown-cast-variable": "Warning",
    "unknown-diag-code": "Warning",
    "unknown-operator": "Warning",
    "unreachable-code": "Hint",
    "unused-function": "Hint",
    "unused-label": "Hint",
    "unused-local": "Hint",
    "unused-vararg": "Hint"
}

diagnostics.unusedLocalExclude

Type: Array<string>

Default: []

Define variable names that will not be reported as an unused local by unused-local.

diagnostics.workspaceDelay

Type: integer

Default: 3000

Define the delay between diagnoses of the workspace in milliseconds. Every time a file is edited, created, deleted, etc. the workspace will be re-diagnosed in the background after this delay. Setting to a negative number will disable workspace diagnostics.

diagnostics.workspaceEvent

Type: string

Default: "OnSave"

Options:

• "OnChange"
• "OnSave"
• "None"

Set when the workspace diagnostics should be analyzed. It can be performed after each change, after a save, or never automatically triggered.

diagnostics.workspaceRate

Type: integer

Default: 100

Define the rate at which the workspace will be diagnosed as a percentage. 100 is 100% speed so the workspace will be diagnosed as fast as possible. The rate can be lowered to reduce CPU usage, but the diagnosis speed will also become slower. The currently opened file will always be diagnosed at 100% speed, regardless of this setting.

doc

Settings for configuring documentation comments.

doc.packageName

Type: Array<string>

Default: []

The pattern used for matching field names as a package-private field. Fields that match any of the patterns provided will be package-private.

doc.privateName

Type: Array<string>

Default: []

The pattern used for matching field names as a private field. Fields that match any of the patterns provided will be private to that class.

doc.protectedName

Type: Array<string>

Default: []

The pattern used for matching field names as a protected field. Fields that match any of the patterns provided will be private to that class and its child classes.

format

Settings for configuring the built-in code formatter.

format.defaultConfig

Type: Object<string, string

Default: {}

The default configuration for the formatter. If there is a .editorconfig in the workspace, it will take priority. Read more on the formatter's GitHub page.

format.enable

Type: boolean

Default: true

Whether the built-in formatted should be enabled or not.

hint

Settings for configuring inline hints

hint.arrayIndex

Type: string

Default: "Auto"

Options:

• "Enable" - Show hint in all tables
• "Auto" - Only show hint when there is more than 3 items or the table is mixed (indexes and keys)
• "Disable" - Disable array index hints

hint.await

Type: boolean

Default: true

If a function has been defined as @async, display an await hint when it is being called.

hint.enable

Type: boolean

Default: false

Whether inline hints should be enabled or not.

hint.paramName

Type: string

Default: "All"

Options:

• "All" - All parameters are hinted
• "Literal" - Only literal type parameters are hinted
• "Disable" - No parameter hints are shown

Whether parameter names should be hinted when typing out a function call.

hint.paramType

Type: boolean

Default: true

Show a hint for parameter types at a function definition. Requires the parameters to be defined with @param

hint.semicolon

Type: string

Default: "SameLine"

Options:

• "All" - Show on every line
• "SameLine" - Show between two statements on one line
• "Disable" - Never hint a semicolon

Whether to show a hint to add a semicolon to the end of a statement.

hint.setType

Type: boolean

Default: false

Show a hint to display the type being applied at assignment operations.

hover

Setting for configuring hover tooltips. The hover tooltips can contain all kinds of useful information.

hover.enable

Type: boolean

Default: true

Whether to enable hover tooltips or not.

hover.enumsLimit

Type: integer

Default: 5

When a value has multiple possible types, hovering it will display them. This setting limits how many will be displayed in the tooltip before they are truncated.

hover.expandAlias

Type: boolean

Default: true

When hovering a value with an @alias for its type, should the alias be expanded into its values. When enabled, ---@alias myType boolean|number appears as boolean|number, otherwise it will appear as myType.

hover.previewFields

Type: integer

Default: 50

When a table is hovered, its fields will be displayed in the tooltip. This setting limits how many fields can be seen in the tooltip. Setting to 0 will disable this feature.

hover.viewNumber

Type: boolean

Default: true

Enable hovering a non-decimal value to see its numeric value.

hover.viewString

Type: boolean

Default: true

Enable hovering a string that contains an escape character to see its true string value. For example, hovering "\x48" will display "H".

hover.viewStringMax

Type: integer

Default: 1000

The maximum number of characters that can be previewed by hovering a string before it is truncated.

misc

Miscellaneous settings that do not belong to any of the other groups.

misc.parameters

Type: Array<string>

Default: []

Command line parameters to be passed along to the server exe when starting through Visual Studio Code.

misc.executablePath

Type: string

Default: ""

Manually specify the path for the Lua Language Server executable file.

runtime

Settings for configuring the runtime environment.

runtime.builtin

Type: Object<library, status>

library Options:

• "basic"
• "bit"
• "bit32"
• "builtin"
• "coroutine"
• "debug"
• "ffi"
• "io"
• "jit"
• "math"
• "os"
• "package"
• "string"
• "table"
• "table.clear"
• "table.new"
• "utf8"

status Options:

• "default" - The library will be enabled if it is a part of the current runtime.version.
• "enable" - Always enable this library
• "disable" - Always disable this library

Default Value

{
    "basic": "default",
    "bit": "default",
    "bit32": "default",
    "builtin": "default",
    "coroutine": "default",
    "debug": "default",
    "ffi": "default",
    "io": "default",
    "jit": "default",
    "math": "default",
    "os": "default",
    "package": "default",
    "string": "default",
    "table": "default",
    "table.clear": "default",
    "table.new": "default",
    "utf8": "default"
}

Set whether each of the builtin Lua libraries is available in the current runtime environment.

runtime.fileEncoding

Type: string

Default: utf8

Options:

• "utf8"
• "ansi" (only available on Windows)
• "utf16le"
• "utf16be"

runtime.meta

Type: string

Default: "${version} ${language} ${encoding}"

🚧 Description needed 🚧

runtime.nonstandardSymbol

Type: Array<string>

Default: []

Options:

• "//"
• "/**/"
• "`"
• "+="
• "-="
• "*="
• "/="
• "%="
• "^="
• "//="
• "|="
• "&="
• "<<="
• ">>="
• "||"
• "&&"
• "!"
• "!="
• "continue"

Add support for non-standard symbols. Make sure to double check that your runtime environment actually supports the symbols you are permitting as standard Lua does not.

runtime.path

Type: Array<string>

Default: ["?.lua", "?/init.lua"]

Defines the paths to use when using require. For example, setting to ?/start.lua will search for <workspace>/myFile/start.lua from the loaded files when doing require"myFile". If runtime.pathStrict is false, <workspace>/**/myFile/start.lua will also be searched. To load files that are not in the current workspace, they will first need to be loaded using workspace.library.

runtime.pathStrict

Type: boolean

Default: false

When enabled, runtime.path will only search the first level of directories. See the description of runtime.path for more info.

runtime.plugin

Type: string

Default: ""

The path to the plugin to use. Blank by default for security reasons.

runtime.pluginArgs

Type: Array<string>

Default: []

Additional arguments that will be passed to the active plugin.

runtime.special

Type: Object<string, string>

Default: {}

Special variables can be set to be treated as other variables. For example, specifying "include" : "require" will result in include being treated like require.

runtime.unicodeName

Type: boolean

Default: false

Whether unicode characters should be allowed in variable names or not.

runtime.version

Type: string

Default: "Lua 5.4"

Options:

• "Lua 5.1"
• "Lua 5.2"
• "Lua 5.3"
• "Lua 5.4"
• "LuaJIT"

The Lua runtime version to use in this environment.

semantic

The semantic group contains settings for semantic colouring in the editor.

semantic.annotation

Type: boolean

Default: true

Whether semantic colouring should be enabled for type annotations.

semantic.enable

Type: boolean

Default: true

Whether semantic colouring should be enabled. You may need to set editor.semanticHighlighting.enabled to true in order for this setting to take effect.

semantic.keyword

Type: boolean

Default: false

Whether the server should provide semantic colouring of keywords, literals, and operators. You should only need to enable this setting if your editor is unable to highlight Lua's syntax.

semantic.variable

Type: boolean

Default: true

Whether the server should provide semantic colouring of variables, fields, and parameters.

signatureHelp

The signatureHelp group contains settings for helping understand signatures.

signatureHelp.enable

Type: boolean

Default: true

🚧 Description needed 🚧

spell

The spell group contains settings that help detect typos and misspellings.

spell.dict

Type: Array<string>

Default: []

A custom dictionary of words that you know are spelt correctly but are being reported as incorrect. Adding words to this dictionary will make them exempt from spell checking.

telemetry

The telemetry group contains settings for the opt-in telemetry.

telemetry.enable

Type: boolean | null

Default: null

The language server comes with opt-in telemetry to help improve the language server. It would be greatly appreciated if you enable this setting. Read the privacy policy before enabling.

type

The type group contains settings for type checking.

type.castNumberToInteger

Type: boolean

Default: false

Whether casting a number to an integer is allowed.

type.weakNilCheck

Type: boolean

Default: false

Whether it is permitted to assign a union type that contains nil to a variable that does not permit it. When false, the following will throw an error because number|nil cannot be assigned to number.

---@alias unionType number|nil

---@type number
local num

---@cast num unionType

type.weakUnionCheck

Type: boolean

Default: false

Whether it is permitted to assign a union type which only has one matching type to a variable. When false, the following will throw an error because string|boolean cannot be assigned to string.

---@alias unionType string|boolean

---@type string
local str = false

window

The window group contains settings that modify the window in VS Code.

window.progressBar

Type: boolean

Default: true

Show a progress bar in the bottom status bar that shows how the workspace loading is progressing.

window.statusBar

Type: boolean

Default: true

Show a Lua 😺 entry in the bottom status bar that can be clicked to manually perform a workspace diagnosis.

workspace

The workspace group contains settings for configuring how the workspace diagnosis works.

workspace.checkThirdParty

Type: boolean

Default: true

Whether third party libraries can be automatically detected and applied. Third party libraries can set up the environment to be as close as possible to your target runtime environment. See meta/3rd to view what third party libraries are currently supported.

workspace.ignoreDir

Type: Array<string>

Default: [".vscode"]

An array of paths that will be ignored and not included in the workspace diagnosis. Uses .gitignore grammar. Can be a file or directory.

workspace.ignoreSubmodules

Type: boolean

Default: true

Whether git submodules should be ignored and not included in the workspace diagnosis.

workspace.library

Type: Array<string>

Default: []

An array of abosolute or workspace-relative paths that will be added to the workspace diagnosis - meaning you will get completion and context from these library files. Can be a file or directory. Files included here will have some features disabled such as renaming fields to prevent accidentally renaming your library files. Read more on the Libraries page.

workspace.maxPreload

Type: integer

Default: 5000

The maximum amount of files that can be diagnosed. More files will require more RAM.

workspace.preloadFileSize

Type: integer

Default: 500

Files larger than this value (in KB) will be skipped when loading for workspace diagnosis.

workspace.supportScheme

Type: Array<string>

Default: ["file", "untitled", "git"]

Lua file schemes to enable the language server for.

workspace.useGitIgnore

Type: boolean

Default: true

Whether files that are in .gitignore should be ignored by the language server when performing workspace diagnosis.

workspace.userThirdParty

Type: Array<string>

Default: []

An array of paths to custom third party libraries. This path should point to a directory where all of your custom libraries are, not just to one of the libraries. If the below is your file structure, this setting should be "myLuaLibraries" - of course this should be an absolute path though.

📦 myLuaLibraries/
    ├── 📂 myCustomLibrary/
    │   ├── 📂 library/
    │   └── 📜 config.lua
    └── 📂 anotherCustomLibrary/
        ├── 📂 library/
        └── 📜 config.lua