Preferences

User-configurable game settings and preferences

The Preferences class provides a centralized store for user-configurable, globally relevant settings. All preferences are automatically persisted to the save file.

Overview

Preferences manages settings such as:

• Display settings (framerate, VSync, debug display)
• Gameplay settings (downscroll, flashing lights, camera zoom)
• Accessibility options (naughtyness filter, subtitles)
• Audio/visual offsets for input lag compensation
• Mobile-specific settings (haptics, screen timeout, controls)

All properties are implemented as static getters/setters that automatically load from and save to the user’s save file.

Display Settings

framerate

Target frames per second for the game.

public static var framerate(get, set):Int

• Web: Always returns 60 (cannot be changed)
• Mobile: Returns the device’s display refresh rate (minimum 60)
• Desktop: User-configurable (default: 60)

Example:

// Get current framerate
trace("Current FPS: " + Preferences.framerate);

// Set framerate (desktop only)
Preferences.framerate = 144;

vsyncMode

VSync mode setting.

public static var vsyncMode(get, set):lime.ui.WindowVSyncMode

vsyncMode · WindowVSyncMode · default: "OFF"

Possible values: OFF, ON, ADAPTIVE

Example:

import lime.ui.WindowVSyncMode;

// Enable VSync
Preferences.vsyncMode = WindowVSyncMode.ON;

// Enable adaptive VSync
Preferences.vsyncMode = WindowVSyncMode.ADAPTIVE;

// Disable VSync
Preferences.vsyncMode = WindowVSyncMode.OFF;

unlockedFramerate

Unlocks the framerate cap on web builds.

public static var unlockedFramerate(get, set):Bool

unlockedFramerate · Bool · default: "false"

Web only. Removes the requestAnimationFrame cap.

Example:

#if web
// Unlock framerate for high refresh rate displays
Preferences.unlockedFramerate = true;
#end

debugDisplay

Controls the debug FPS/memory counter visibility.

public static var debugDisplay(get, set):DebugDisplayMode

debugDisplay · DebugDisplayMode · default: "Off"

Possible values: Off, On, Advanced

Example:

// Show basic debug display
Preferences.debugDisplay = DebugDisplayMode.On;

// Show advanced debug display with additional info
Preferences.debugDisplay = DebugDisplayMode.Advanced;

// Hide debug display
Preferences.debugDisplay = DebugDisplayMode.Off;

debugDisplayBGOpacity

Background opacity for the debug display.

public static var debugDisplayBGOpacity(get, set):Int

debugDisplayBGOpacity · Int · default: "50"

Value from 0-100 representing background opacity percentage.

Example:

// Set semi-transparent background
Preferences.debugDisplayBGOpacity = 50;

// Fully opaque background
Preferences.debugDisplayBGOpacity = 100;

// Transparent background
Preferences.debugDisplayBGOpacity = 0;

Gameplay Settings

downscroll

Places the strumline at the bottom of the screen instead of the top.

public static var downscroll(get, set):Bool

downscroll · Bool · default: "false"

Desktop default: false. Mobile default: true.

Example:

// Enable downscroll
Preferences.downscroll = true;

// Check downscroll state
if (Preferences.downscroll)
{
  trace("Strumline is at bottom");
}

flashingLights

Controls the intensity of flashing lights effects.

public static var flashingLights(get, set):Bool

flashingLights · Bool · default: "true"

When false, flashing lights in menus and gameplay are less intense.

Example:

// Disable flashing lights for accessibility
Preferences.flashingLights = false;

zoomCamera

Enables camera zoom synchronized to the beat.

public static var zoomCamera(get, set):Bool

zoomCamera · Bool · default: "true"

When true, the camera bumps on beats during gameplay.

Example:

// Disable camera zoom
Preferences.zoomCamera = false;

naughtyness

Controls whether explicit language is displayed.

public static var naughtyness(get, set):Bool

naughtyness · Bool · default: "true"

When false, filters explicit content. Always false if compiled with NO_FEATURE_NAUGHTYNESS.

Example:

// Enable content filter
Preferences.naughtyness = false;

subtitles

Enables subtitles during songs and cutscenes.

public static var subtitles(get, set):Bool

subtitles · Bool · default: "true"

When true, displays subtitles when available.

Example:

// Enable subtitles
Preferences.subtitles = true;

Audio/Visual Settings

globalOffset

Global audio offset to compensate for input lag.

public static var globalOffset(get, set):Int

globalOffset · Int · default: "0"

Offset in milliseconds. Positive values make notes appear earlier.

Example:

// Add 50ms offset for input lag
Preferences.globalOffset = 50;

// Negative offset makes notes appear later
Preferences.globalOffset = -25;

strumlineBackgroundOpacity

Opacity of the background behind the notes.

public static var strumlineBackgroundOpacity(get, set):Int

strumlineBackgroundOpacity · Int · default: "0"

Value from 0-100. 0 = transparent, 100 = fully opaque black.

Example:

// Add semi-transparent background behind notes
Preferences.strumlineBackgroundOpacity = 50;

// Remove background
Preferences.strumlineBackgroundOpacity = 0;

System Settings

autoPause

Automatically pauses the game when tabbing out.

public static var autoPause(get, set):Bool

autoPause · Bool · default: "true"

When true, game pauses on focus loss. Always false on mobile.

Example:

// Disable auto-pause
Preferences.autoPause = false;

autoFullscreen

Automatically launches in fullscreen on startup.

public static var autoFullscreen(get, set):Bool

autoFullscreen · Bool · default: "true"

When true, game starts in fullscreen mode.

Example:

// Start in windowed mode
Preferences.autoFullscreen = false;

Screenshot Settings

shouldHideMouse

Hides the mouse cursor when taking screenshots.

public static var shouldHideMouse(get, set):Bool

shouldHideMouse · Bool · default: "true"

When true, mouse cursor is hidden during screenshot capture.

fancyPreview

Shows a preview after taking a screenshot.

public static var fancyPreview(get, set):Bool

fancyPreview · Bool · default: "true"

When true, displays an animated preview of the screenshot.

previewOnSave

Only shows preview after the screenshot is successfully saved.

public static var previewOnSave(get, set):Bool

previewOnSave · Bool · default: "true"

When true, preview only appears after save completes.

Example:

// Configure screenshot behavior
Preferences.shouldHideMouse = true;
Preferences.fancyPreview = true;
Preferences.previewOnSave = false; // Show preview immediately

Mobile Settings

These settings are only available when compiled with mobile support (#if mobile).

hapticsMode

Controls haptic feedback mode.

public static var hapticsMode(get, set):HapticsMode

hapticsMode · HapticsMode · default: "All"

Possible values: NONE, NOTES_ONLY, ALL

Example:

#if mobile
// Enable haptics only for note hits
Preferences.hapticsMode = HapticsMode.NOTES_ONLY;

// Enable all haptic feedback
Preferences.hapticsMode = HapticsMode.ALL;

// Disable haptics
Preferences.hapticsMode = HapticsMode.NONE;
#end

hapticsIntensityMultiplier

Multiplier for haptic feedback intensity.

public static var hapticsIntensityMultiplier(get, set):Float

hapticsIntensityMultiplier · Float · default: "1.0"

Multiplier for all haptic effects. Higher values = stronger vibration.

Example:

#if mobile
// Increase haptic intensity
Preferences.hapticsIntensityMultiplier = 2.5;

// Decrease intensity
Preferences.hapticsIntensityMultiplier = 0.5;
#end

screenTimeout

Allows the device screen to sleep.

public static var screenTimeout(get, set):Bool

screenTimeout · Bool · default: "false"

When false, prevents screen from sleeping during gameplay.

Example:

#if mobile
// Allow screen to sleep
Preferences.screenTimeout = true;
#end

controlsScheme

Control scheme for the hitbox on mobile.

public static var controlsScheme(get, set):String

controlsScheme · String · default: "Arrows"

Control layout type. Default is arrow key layout.

Example:

#if mobile
// Change control scheme
Preferences.controlsScheme = FunkinHitboxControlSchemes.Arrows;
#end

Initialization

init()

Initializes preferences and applies saved settings.

public static function init():Void

This method is called automatically during game startup. It:

• Applies the autoPause setting
• Sets up the debug display
• Configures framerate caps
• Sets mobile-specific options

Example:

// Usually called in Main.hx during initialization
Preferences.init();

Example: Settings Menu

import funkin.Preferences;
import flixel.FlxG;
import flixel.text.FlxText;
import flixel.ui.FlxButton;

class SettingsMenu extends MusicBeatState
{
  override function create():Void
  {
    super.create();
    
    var yPos = 50;
    
    // Downscroll toggle
    var downscrollBtn = new FlxButton(100, yPos, "Downscroll: " + Preferences.downscroll, function()
    {
      Preferences.downscroll = !Preferences.downscroll;
      downscrollBtn.text = "Downscroll: " + Preferences.downscroll;
    });
    add(downscrollBtn);
    yPos += 50;
    
    // Flashing lights toggle
    var flashBtn = new FlxButton(100, yPos, "Flashing Lights: " + Preferences.flashingLights, function()
    {
      Preferences.flashingLights = !Preferences.flashingLights;
      flashBtn.text = "Flashing Lights: " + Preferences.flashingLights;
    });
    add(flashBtn);
    yPos += 50;
    
    // Global offset adjustment
    var offsetText = new FlxText(100, yPos, 0, "Global Offset: " + Preferences.globalOffset + "ms");
    add(offsetText);
    
    var offsetPlus = new FlxButton(300, yPos, "+10ms", function()
    {
      Preferences.globalOffset += 10;
      offsetText.text = "Global Offset: " + Preferences.globalOffset + "ms";
    });
    add(offsetPlus);
    
    var offsetMinus = new FlxButton(400, yPos, "-10ms", function()
    {
      Preferences.globalOffset -= 10;
      offsetText.text = "Global Offset: " + Preferences.globalOffset + "ms";
    });
    add(offsetMinus);
  }
}

Example: Performance Optimization

import funkin.Preferences;

class PerformanceSettings
{
  public static function applyLowEndSettings():Void
  {
    // Disable camera zoom for better performance
    Preferences.zoomCamera = false;
    
    // Disable flashing lights (reduces rendering load)
    Preferences.flashingLights = false;
    
    #if !mobile
    // Lower framerate on desktop
    Preferences.framerate = 60;
    #end
  }
  
  public static function applyHighEndSettings():Void
  {
    // Enable all visual effects
    Preferences.zoomCamera = true;
    Preferences.flashingLights = true;
    
    #if !mobile
    // Unlock high framerates
    Preferences.framerate = 144;
    #end
  }
}

Best Practices

Auto-Save

Preferences automatically save when changed. No manual save call needed:

// This automatically saves to the save file
Preferences.downscroll = true;

Platform-Specific Settings

Check platform before setting platform-specific preferences:

#if mobile
Preferences.hapticsMode = HapticsMode.ALL;
#end

#if web
Preferences.unlockedFramerate = true;
#end

#if desktop
Preferences.framerate = 144;
#end

Validation

Validate user input when allowing custom values:

// Clamp offset to reasonable range
var newOffset = userInput;
if (newOffset < -200) newOffset = -200;
if (newOffset > 200) newOffset = 200;
Preferences.globalOffset = newOffset;

See Also

• Conductor - Uses globalOffset for timing