Skip to content

Configuration

VukeFN edited this page Aug 15, 2026 · 12 revisions

Configuration

Settings are organized into logical sections for easier navigation. Access via Ctrl+, and search "Verse Auto Imports".

Table of Contents


General Settings

Core functionality settings:

Setting Default Description
general.autoImport true Enable/disable automatic importing
general.autoImportDebounceDelay 3000 Debounce delay (ms) - waits this long after you stop typing before auto-importing
general.autoImportScope "allFiles" Which documents automatic imports may edit
general.diagnosticDelay 1000 Deprecated - use autoImportDebounceDelay. Delay (ms) before processing errors

general.diagnosticDelay is marked deprecated to VS Code itself, so the settings editor leaves it out of the list unless you have set it, and flags the value with the replacement's name where you have. A value you set explicitly is still honored while autoImportDebounceDelay is unset.

Auto Import Scope

Bounds which files an automatic import is allowed to edit. Quick fixes and CodeLens are unaffected by this setting and stay available everywhere.

{
    "verseAutoImports.general.autoImportScope": "allFiles"
}
Value Description
"allFiles" Edit any project file the compiler reports an error for, including files you never opened (default)
"openFiles" Restrict edits to documents you have open
"activeFile" Restrict edits to the editor you were working in when the compiler reported the error

Import Behavior

Control how imports are handled:

Setting Default Description
behavior.importSyntax "curly" Use using { /Path } or using. /Path
behavior.preserveImportLocations true Keep existing imports where they are
behavior.sortImportsAlphabetically true Sort imports by rank (absolute paths, then bare local, then dotted local) rather than plain alphabetical order, because Verse import order is semantic
behavior.importGrouping "none" Group digest vs local imports
behavior.emptyLinesAfterImports 1 Number of empty lines after imports (-1 to 5; -1 leaves the existing spacing untouched)
behavior.multiOptionStrategy "quickfix" How to handle multiple import options
behavior.ambiguousImports {} Preferred paths for ambiguous classes; empty by default, so the list is exactly what you configure
behavior.digestImportPrefixes [...] Path prefixes that identify digest imports

Import Grouping Options

Control how imports are organized and grouped:

{
    "verseAutoImports.behavior.importGrouping": "none"
}
Value Description
"none" All imports are mixed together (default)
"digestFirst" Digest imports first, then local imports with a blank line separator
"localFirst" Local imports first, then digest imports with a blank line separator

Example with "digestFirst":

using { /Fortnite.com/Devices }
using { /UnrealEngine.com/Temporary/SpatialMath }
using { /Verse.org/Simulation }

using { Utils }
using { Components.PlayerManager }

Grouping never overrides what Verse can resolve. Under "localFirst", a digest import that a relative import resolves through is kept above that relative import rather than moved below it, because the order the group asks for would produce a file that does not compile.

Empty Lines After Imports

Control the spacing between imports and code:

{
    "verseAutoImports.behavior.emptyLinesAfterImports": 1
}
Value Description
-1 Leave the spacing after the imports exactly as you wrote it
0 No empty line between imports and code
1 One empty line (default, recommended)
2-5 Multiple empty lines for additional visual separation

At 0 the extension deletes the empty lines after your imports; use -1 if what you want is for it to stop adjusting the spacing at all.

The value is a whole number of lines. A fractional value already saved in your settings rounds to the nearest whole number.

Every value except -1 is automatically applied:

  • When saving files
  • When adding new imports (auto-import or quick fix)
  • When running "Optimize Imports" command

Multi-Option Strategies

{
    "verseAutoImports.behavior.multiOptionStrategy": "quickfix"
}
Value Description
"quickfix" Show quick fix menu (recommended)
"auto_shortest" Automatically choose shortest path
"auto_first" Automatically choose first option
"disabled" Ignore multi-option scenarios

Quick Fix Settings

Quick fix menu customization:

Setting Default Description
quickFix.sortAlphabetically false Sort quick fix options alphabetically
quickFix.showDescriptions false Show descriptions in quick fix menu

Path Conversion

Absolute/relative path conversion settings:

Setting Default Description
pathConversion.enableCodeLens true Show CodeLens actions to convert paths
pathConversion.codeLensVisibility "hover" When to show CodeLens: "hover" or "always"
pathConversion.codeLensHideDelay 1000 Milliseconds before hiding CodeLens after leaving hover (hover mode). Accepts 500-10000

Module Visibility

Where the Make Module Public quick fix writes a declaration when the module has none:

Setting Default Description
moduleVisibility.definitionsFileName "_definitions.verse" Name of the file at the Content root that new <public> module declarations are written into

A module that already has an explicit declaration is edited where it stands, whatever this is set to. See Module Visibility for the feature itself.


Experimental Features

Warning: These features are experimental and may not always provide accurate suggestions.

Setting Default Description
experimental.useDigestFiles false Use digest files for suggestions

Cache Settings

Project path tree caching settings for faster module resolution:

Setting Default Description
cache.enableProjectCache true Enable project path tree caching for faster module resolution
cache.autoRebuildOnStartup false Automatically rebuild cache on VS Code startup
cache.watcherDebounceMs 500 File watcher debounce delay (100-5000ms)

Cache Behavior

The cache stores parsed identifiers from all .verse files in your project:

{
    "verseAutoImports.cache.enableProjectCache": true,
    "verseAutoImports.cache.autoRebuildOnStartup": false,
    "verseAutoImports.cache.watcherDebounceMs": 500
}
Setting Description
enableProjectCache When enabled, the extension builds and maintains a path tree of your project for faster lookups. Turning it off drops any stored cache and makes the rebuild, clear and status commands report the cache as off; changing it offers the window reload it needs
autoRebuildOnStartup Forces a full cache rebuild when VS Code starts (slower startup but ensures fresh cache)
watcherDebounceMs How long to wait after file changes before updating the cache (prevents excessive updates during rapid saves)

Multi-Root Workspaces

A workspace with several folders can set some of these settings per folder, and the extension reads the value belonging to the folder the edited file sits in — not the first folder's. The rest are read once for the window.

Per folder:

Setting Read from
general.autoImport the folder holding the file
behavior.importSyntax the folder holding the file
behavior.preserveImportLocations the folder holding the file
behavior.sortImportsAlphabetically the folder holding the file
behavior.importGrouping the folder holding the file
behavior.emptyLinesAfterImports the folder holding the file
behavior.multiOptionStrategy the folder holding the file
quickFix.sortAlphabetically the folder holding the file
quickFix.showDescriptions the folder holding the file
pathConversion.enableCodeLens the folder holding the file
moduleVisibility.definitionsFileName the folder holding the file

Once for the window: everything under cache., experimental.useDigestFiles, behavior.ambiguousImports, behavior.digestImportPrefixes, general.autoImportDebounceDelay, general.autoImportScope, general.diagnosticDelay, pathConversion.codeLensVisibility and pathConversion.codeLensHideDelay.

So two folders can use different import syntax, different grouping, or a different definitions file name, and each file is written the way its own folder asks for. The quick fix menu labels an import in that folder's syntax as well, matching the text it inserts.


Full Configuration Reference

All settings with their full paths:

{
    "verseAutoImports.general.autoImport": true,
    "verseAutoImports.general.autoImportDebounceDelay": 3000,
    "verseAutoImports.general.autoImportScope": "allFiles",
    "verseAutoImports.general.diagnosticDelay": 1000,
    "verseAutoImports.behavior.importSyntax": "curly",
    "verseAutoImports.behavior.preserveImportLocations": true,
    "verseAutoImports.behavior.sortImportsAlphabetically": true,
    "verseAutoImports.behavior.importGrouping": "none",
    "verseAutoImports.behavior.emptyLinesAfterImports": 1,
    "verseAutoImports.behavior.multiOptionStrategy": "quickfix",
    "verseAutoImports.behavior.ambiguousImports": {},
    "verseAutoImports.behavior.digestImportPrefixes": [
        "/Verse.org/",
        "/Fortnite.com/",
        "/UnrealEngine.com/"
    ],
    "verseAutoImports.quickFix.sortAlphabetically": false,
    "verseAutoImports.quickFix.showDescriptions": false,
    "verseAutoImports.pathConversion.enableCodeLens": true,
    "verseAutoImports.pathConversion.codeLensVisibility": "hover",
    "verseAutoImports.pathConversion.codeLensHideDelay": 1000,
    "verseAutoImports.moduleVisibility.definitionsFileName": "_definitions.verse",
    "verseAutoImports.experimental.useDigestFiles": false,
    "verseAutoImports.cache.enableProjectCache": true,
    "verseAutoImports.cache.autoRebuildOnStartup": false,
    "verseAutoImports.cache.watcherDebounceMs": 500
}

Clone this wiki locally