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 is split into two Polymod Module classes per edition: one that handles real-time gameplay logic (layout, HUD sprites, score counter) and one that handles menu injection (Options menu page and pause menu modifications). Keeping these concerns separate means the gameplay module can run at a high priority without interfering with options page setup, and the options module can be lightweight since it only fires on state transitions.

​
Module Classes

Each edition ships exactly two modules. The gameplay module is given a high priority so its onUpdate callback runs late in the frame; the options module uses the default priority because it only reacts to state change events.

VExtendedGameplayModule

Edition: PCPriority: 1200Handles all real-time gameplay logic during a PlayState session: middlescroll strumline positioning, opponent note opacity, strumline lane backgrounds, the song progress time bar, and the detailed score counter. Constructs and destroys HUD sprites as PlayState instances come and go.

VExtendedOptionsModule

Edition: PCPriority: defaultInjects the V-Extended preferences page into OptionsState and optionally adds Options and Botplay entries to the standard pause menu. Manages the return-to-song flow when Options is opened from pause.

VExtendedMobileGameplayModule

Edition: MobilePriority: 1200Same role as the PC gameplay module but with mobile-specific optimisations: the score counter update is throttled to once every 50 ms (scoreUpdateTimer >= 0.05) and is driven by a scoreDirty flag set by onNoteHit and onNoteMiss. Opponent strumline remapping uses a simpler offset approach instead of the full PC layout tracker.

VExtendedMobileOptionsModule

Edition: MobilePriority: defaultSame role as the PC options module plus fitMobilePauseMenu(), which redistributes pause menu entries vertically when extra items are injected to prevent overflow on smaller screens.
The gameplay module priority of 1200 is intentionally high to ensure V-Extended’s onUpdate runs after most other modules. FNF’s default module priority is 0; a module with priority 1200 receives update callbacks later in the same frame, so V-Extended can read finalised strumline positions before writing HUD positions.

​
Class Declaration

Both gameplay modules follow this pattern — the priority is passed directly to the parent Module constructor, and loadOptions() is called immediately so that saved preferences are ready before the first onUpdate fires: 
class VExtendedGameplayModule extends Module
{
    public function new()
    {
        super("VExtendedGameplayModule", 1200);
        loadOptions();
    }
}

​
Event Hooks

V-Extended uses eight distinct Polymod event hooks across its four module classes.
EventModule(s)Purpose
onSubStateOpenEnd(event)Options (PC & Mobile)Intercepts PauseSubState opens in Standard mode; injects Options and/or Botplay entries into the pause menu when the corresponding preferences are enabled. Mobile also calls fitMobilePauseMenu() to prevent layout overflow.
onStateChangeEnd(event)Options (PC & Mobile)Intercepts transitions to OptionsState to inject the V-Extended preferences page into the options codex. Also wires the return-to-song callback when opened from pause. Gameplay modules call loadOptions() and destroyHud() on non-PlayState transitions.
onNoteGhostMiss(event)Gameplay (PC only)Calls event.cancel() when ghost tapping is enabled, preventing empty direction presses from registering as misses.
onNoteHit(event)Gameplay (PC & Mobile)In botplay mode, triggers note splash and hold cover animations on the player strumline. On Mobile, also sets scoreDirty = true to schedule a score counter refresh.
onNoteMiss(event)Gameplay (Mobile only)Sets scoreDirty = true so the throttled score counter is refreshed on the next eligible frame.
onSongEnd(event)Gameplay (PC & Mobile)In botplay mode (and not charting mode), calls event.cancel() to suppress the default end-of-song flow, then navigates directly to FreeplayState.
onUpdate(event)Gameplay (PC & Mobile)Per-frame driver: applies middlescroll layout and opponent opacity, creates/updates/destroys strumline backgrounds, time bar, and score counter sprites based on current preferences and PlayState availability.
onDestroy(event)Gameplay (PC & Mobile)Calls destroyHud() to remove and null all HUD sprites, preventing memory leaks when the module is torn down.

​
HUD Z-Index Layers

V-Extended inserts custom FlxSprite instances at specific z-index values so they sit above the game scene camera but below the native FNF HUD elements. All sprites are assigned to state.camHUD and have scrollFactor set to (0, 0).
Z-IndexSpriteDescription
700opponentStrumBackgroundDark lane background behind the opponent strumline
701playerStrumBackgroundDark lane background behind the player strumline
803scorePrefixTextScore / misses / accuracy prefix segment of the detailed score counter
804scoreRankTextRank letter (P / E / G / L) rendered in its rank colour
805scoreSuffixTextClosing bracket ] of the detailed score counter
1200barBackgroundDark background rectangle of the song progress time bar
1201barFillWhite fill rectangle scaled along the X axis to show song progress
1202barLabelVCR bitmap font label showing song name, difficulty, or time
If another mod conflicts with V-Extended’s HUD layers — for example, a mod that places sprites at z-index 700 or 1200 — you can resolve the conflict by editing the zIndex values assigned in createStrumlineBackgrounds(), createTimeBar(), and createScoreCounter() inside the relevant .hxc source file.

Build docs developers (and LLMs) love

Get started for freeTalk to us