Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/misterfnflover787/v-extended-fnf/llms.txt

Use this file to discover all available pages before exploring further.

V-Extended stores all of its settings in FNF V-Slice’s built-in Save.instance.modOptions map. The PC edition writes to the key "vExtended" and the Mobile edition writes to a separate key "vExtendedMobile", so both modpacks can coexist in the same save file without overwriting each other. Settings are initialised with defaults on first launch via ensureSave() and persisted immediately after every preference change via Save.instance.flush().
Directly editing the FNF save file on disk is not recommended. The save format is subject to change between FNF updates and malformed data may prevent your preferences from loading correctly. Use the in-game Options → V-Extended menu to change all settings safely.

​
Reading and Writing Settings

The following snippet shows how to read from and write to the V-Extended save object programmatically, for example from another Polymod script: 
// Read
var save = Save.instance.modOptions.get("vExtended");
var ghostEnabled:Bool = save.ghostTappingEnabled; // true by default

// Write
save.ghostTappingEnabled = false;
Save.instance.flush();

​
PC Save Key: vExtended

All 17 fields below are stored under Save.instance.modOptions.get("vExtended").
​
ghostTappingEnabled
Bool
When true, empty direction presses (no note present) do not count as misses. Migrated automatically from the legacy key ghostTapping.enabled if that key exists in the save.Default: true
​
pauseMenuOptionsEnabled
Bool
When true, an Options entry is injected into the standard pause menu. Selecting it opens OptionsState and returns to the current song on exit.Default: false
​
pauseMenuBotplayEnabled
Bool
When true, an Enable Botplay / Disable Botplay toggle is injected into the standard pause menu. Selecting it restarts the song with botplay flipped.Default: false
​
middlescrollEnabled
Bool
When true, the player strumline is centred horizontally and the opponent notes are split to the far left and far right of the screen.Default: false
​
opponentNotesOpacity
Float
Controls the maximum alpha applied to opponent receptors, notes, and sustain trails. A value of 100 is fully opaque; 0 makes opponent notes invisible.Default: 100 | Range: 0 – 100 | Step: 5
​
strumlineBackgroundEnabled
Bool
When true, a dark grey (#2B2B2B) lane background sprite is rendered behind each strumline, above the game scene and below the HUD.Default: false
​
strumlineBackgroundOpacity
Float
Controls the alpha of the strumline background sprites.Default: 35 | Range: 0 – 100 | Step: 5
​
timeBarEnabled
Bool
When true, a song progress bar is drawn near the strumline (above on upscroll, below on downscroll).Default: true
​
timeBarDisplayMode
Int
Selects the label text shown over the time bar fill.
ValueLabel
0Song Name
1Song Name + Difficulty
2Time Left (countdown)
3Time Elapsed
4Nothing (bar only)
Migrated automatically from the legacy key vslice-time-bar.displayMode if that key exists.Default: 0 | Range: 0 – 4
​
timeBarWidth
Int
Width of the time bar fill area in pixels. The background is 4 px wider on each side.Default: 520 | Range: 320 – 760 | Step: 20
​
timeBarHeight
Int
Height of the time bar fill area in pixels.Default: 14 | Range: 8 – 24 | Step: 2
​
timeBarVerticalOffset
Int
Additional downward offset applied to the time bar position in pixels. Added on top of the automatic upscroll/downscroll placement.Default: 8 | Range: 0 – 24 | Step: 2
​
timeBarOpacity
Float
Alpha of the dark time bar background rectangle. The fill and label are always fully opaque.Default: 72 | Range: 20 – 100 | Step: 5
​
detailedScoreEnabled
Bool
When true, replaces the standard FNF score text with a custom counter showing score, missed notes, accuracy percentage, and a Freeplay-style rank letter (P / E / G / L).Default: true
​
scoreOutlineEnabled
Bool
When true, adds a black outline to all three score counter text objects using FlxTextBorderStyle.OUTLINE.Default: true
​
scoreOutlineSize
Float
Thickness of the score counter outline in pixels.Default: 2 | Range: 1 – 4 | Step: 1
​
accuracyDecimals
Int
Number of decimal places shown for the accuracy percentage in the detailed score counter.
ValueExample
097%
197.4%
297.42%
Default: 2 | Range: 0 – 2

​
Mobile Save Key: vExtendedMobile

The Mobile edition uses a separate save key, Save.instance.modOptions.get("vExtendedMobile"). Most fields are functionally identical to their PC counterparts; only the differences and mobile-exclusive fields are documented in full below. For shared fields (pauseMenuOptionsEnabled, pauseMenuBotplayEnabled, opponentNotesOpacity, strumlineBackgroundEnabled, strumlineBackgroundOpacity, timeBarEnabled, timeBarDisplayMode, timeBarWidth, timeBarHeight, timeBarVerticalOffset, timeBarOpacity, detailedScoreEnabled, scoreOutlineEnabled, scoreOutlineSize, accuracyDecimals), see the PC Save Key section above — defaults and ranges are identical.

​
Mobile-only fields

​
alternativeInputEnabled
Bool
When true, switches FNF’s active controls scheme to "Four Lanes" on load, turning the full screen into four touch lanes while keeping both strumlines in the standard desktop layout. The previous scheme is stored in previousControlsScheme so it can be restored when the option is disabled.Default: false
​
previousControlsScheme
String
Stores the name of the controls scheme that was active before Alternative Note Input was enabled, so it can be restored when the option is toggled off. Not directly user-configurable; managed automatically by the alternativeInputEnabled toggle.Default: "Arrows"
​
strumlineBackgroundPadding
Int
Controls how many pixels the strumline background extends beyond the outermost receptor on each side. The PC edition uses a fixed 16 px padding; the Mobile edition exposes this as a configurable value.Default: 14 | Range: 0 – 40 | Step: 2

​
Fields not present in Mobile

The following PC fields do not exist in the vExtendedMobile save object and have no effect in the Mobile edition:
  • ghostTappingEnabled — ghost tapping is not configurable on Mobile; the onNoteGhostMiss hook is not registered.
  • middlescrollEnabled — the Mobile edition does not implement middlescroll; opponent note repositioning uses a fixed 48 px left-shift instead.

​
Migration

V-Extended automatically migrates two legacy preference keys from older mod versions. Migration runs inside ensureSave() the first time the save object is accessed after an upgrade, and only if the new field is still null.

​
ghostTapping.enabled → vExtended.ghostTappingEnabled

Earlier versions of V-Extended stored ghost tapping state in a separate top-level modOptions key named ghostTapping: 
// Legacy storage (old versions)
var oldGhost = Save.instance.modOptions.get("ghostTapping");
// oldGhost.enabled == true/false

// Current storage
Save.instance.modOptions.get("vExtended").ghostTappingEnabled
On first load after upgrading, V-Extended reads ghostTapping.enabled and copies its value into vExtended.ghostTappingEnabled. If the old key is absent, the default value of true is used.

​
vslice-time-bar.displayMode → vExtended.timeBarDisplayMode

The time bar display mode was previously stored under a separate key named vslice-time-bar: 
// Legacy storage (old versions)
var oldTimeBar = Save.instance.modOptions.get("vslice-time-bar");
// oldTimeBar.displayMode == 0..4

// Current storage
Save.instance.modOptions.get("vExtended").timeBarDisplayMode
On first load after upgrading, V-Extended reads vslice-time-bar.displayMode and copies its value into vExtended.timeBarDisplayMode. If the old key is absent, the default value of 0 (Song Name) is used. This migration only applies to the PC edition; the Mobile edition initialises timeBarDisplayMode directly to 0 with no legacy fallback.

Build docs developers (and LLMs) love

Get started for freeTalk to us