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
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
Web only. Removes the requestAnimationFrame cap.
#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
// 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
Value from 0-100 representing background opacity percentage.
// Set semi-transparent background
Preferences.debugDisplayBGOpacity = 50;
// Fully opaque background
Preferences.debugDisplayBGOpacity = 100;
// Transparent background
Preferences.debugDisplayBGOpacity = 0;
Gameplay Settings
Places the strumline at the bottom of the screen instead of the top.
public static var downscroll(get, set):Bool
Desktop default: false. Mobile default: true.
// 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
When false, flashing lights in menus and gameplay are less intense.
// Disable flashing lights for accessibility
Preferences.flashingLights = false;
zoomCamera
Enables camera zoom synchronized to the beat.
public static var zoomCamera(get, set):Bool
When true, the camera bumps on beats during gameplay.
// Disable camera zoom
Preferences.zoomCamera = false;
naughtyness
Controls whether explicit language is displayed.
public static var naughtyness(get, set):Bool
When false, filters explicit content. Always false if compiled with NO_FEATURE_NAUGHTYNESS.
// Enable content filter
Preferences.naughtyness = false;
subtitles
Enables subtitles during songs and cutscenes.
public static var subtitles(get, set):Bool
When true, displays subtitles when available.
// Enable subtitles
Preferences.subtitles = true;
Audio/Visual Settings
globalOffset
Global audio offset to compensate for input lag.
public static var globalOffset(get, set):Int
Offset in milliseconds. Positive values make notes appear earlier.
// 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
Value from 0-100. 0 = transparent, 100 = fully opaque black.
// 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
When true, game pauses on focus loss. Always false on mobile.
// Disable auto-pause
Preferences.autoPause = false;
autoFullscreen
Automatically launches in fullscreen on startup.
public static var autoFullscreen(get, set):Bool
When true, game starts in fullscreen mode.
// Start in windowed mode
Preferences.autoFullscreen = false;
Screenshot Settings
shouldHideMouse
Hides the mouse cursor when taking screenshots.
public static var shouldHideMouse(get, set):Bool
When true, mouse cursor is hidden during screenshot capture.
fancyPreview
Shows a preview after taking a screenshot.
public static var fancyPreview(get, set):Bool
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
When true, preview only appears after save completes.
// 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
Possible values: NONE, NOTES_ONLY, ALL
#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
Multiplier for all haptic effects. Higher values = stronger vibration.
#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
When false, prevents screen from sleeping during gameplay.
#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
Control layout type. Default is arrow key layout.
#if mobile
// Change control scheme
Preferences.controlsScheme = FunkinHitboxControlSchemes.Arrows;
#end
Initialization
init()
Initializes preferences and applies saved settings.
public static function init():Void
- 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();
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);
}
}
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;
#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
