Skip to main content
StepMania uses a comprehensive preferences system to store user settings, game configuration, and behavior options. Preferences can be configured through the options menu, modified via Lua, or set using command-line arguments.

​
Preference Storage

Preferences are stored in the Preferences.ini file in the StepMania save directory. The file uses INI format with sections and key-value pairs.

​
Preference Types

StepMania supports several preference types:
  • String: Text values (e.g., theme names, language codes)
  • Integer: Whole numbers (e.g., screen width, coins per credit)
  • Float: Decimal numbers (e.g., global offset, difficulty scale)
  • Boolean: True/false values (e.g., windowed mode, show stats)
  • Enum: Predefined set of values (e.g., image cache mode, background fit mode)

​
Core Display Preferences

PreferenceTypeDescription
WindowedboolRun in windowed mode instead of fullscreen
DisplayIdstringIdentifier for the display to use
DisplayWidthintScreen resolution width
DisplayHeightintScreen resolution height
DisplayAspectRatiofloatAspect ratio for rendering
DisplayColorDepthintColor depth for display
RefreshRateintMonitor refresh rate
VsyncboolEnable vertical sync
FullscreenIsBorderlessWindowboolUse borderless window for fullscreen
ShowMouseCursorboolDisplay mouse cursor

​
Graphics & Rendering

PreferenceTypeDescription
TextureColorDepthintColor depth for textures
MovieColorDepthintColor depth for videos
StretchBackgroundsboolStretch backgrounds to fit screen
BGFitModeenumHow backgrounds are fitted
HighResolutionTexturesenumHigh-res texture loading mode
MaxTextureResolutionintMaximum texture resolution
AllowMultitextureboolEnable multitexture support
FastNoteRenderingboolUse optimized note rendering
ImageCacheenumImage caching mode
DelayedTextureDeleteboolDefer texture deletion
DelayedModelDeleteboolDefer model deletion
FastLoadboolEnable fast loading
FastLoadAdditionalSongsboolFast load for additional songs

​
Gameplay Settings

PreferenceTypeDescription
CurrentGamestringCurrently selected game type
DefaultModifiersstringDefault player modifiers
LifeDifficultyScalefloatScale for life difficulty
RateModsAffectTweensboolRate mods affect UI animations
RegenComboAfterMissintCombo needed to regenerate life
MaxRegenComboAfterMissintCap for regen combo
MercifulDrainboolScale negative life by current life
HarshHotLifePenaltyboolStricter life penalty when near full
MinTNSToHideNotesenumMinimum judgment to hide notes
BreakComboToGetItemboolBreaking combo grants items

​
Course & Stage Options

PreferenceTypeDescription
Minimum1FullSongInCoursesboolFirst song uses FEOS, then fail immediately
FailOffInBeginnerboolDisable failing in Beginner difficulty
FailOffForFirstStageEasyboolDisable failing in first stage Easy
MercifulBeginnerboolEasier grading in Beginner
ComboContinuesBetweenSongsboolCombo persists between songs
LockCourseDifficultiesboolLock difficulties in courses
ProgressiveLifebarintProgressive lifebar mode
ProgressiveStageLifebarintStage-based progressive lifebar
ProgressiveNonstopLifebarintNonstop progressive lifebar

​
User Interface

PreferenceTypeDescription
ThemestringCurrent theme name
AnnouncerstringCurrent announcer
ShowStatsboolDisplay statistics
ShowBannersboolShow song banners
ShowInstructionsboolShow mode instructions
ShowCautionboolShow caution screen
ShowNativeLanguageboolDisplay native language
MenuTimerboolEnable menu timer
DelayedBackboolDelay back button
AllowHoldForOptionsboolHold button for options
ThreeKeyNavigationboolThree-key navigation mode
ShowDancingCharactersenumDancing character display mode

​
Music Wheel

PreferenceTypeDescription
MusicWheelUsesSectionsenumUse sections in music wheel
MusicWheelSwitchSpeedintMusic wheel scroll speed
OnlyPreferredDifficultiesboolShow only preferred difficulties
HiddenSongsboolEnable hidden songs

​
Scoring & Grading

PreferenceTypeDescription
AllowW1enumAllow Flawless (W1) timing
PercentageScoringboolUse percentage-based scoring
MinPercentageForMachineSongHighScorefloatMin % for song high score
MinPercentageForMachineCourseHighScorefloatMin % for course high score
DisqualificationboolEnable score disqualification
MercifulSuperMeterboolScale super meter by life

​
Arcade & Credits

PreferenceTypeDescription
EventModeboolEnable event mode
CoinsPerCreditintCoins required per credit
SongsPerPlayintSongs per credit
DelayedCreditsReconcileboolDelay credit reconciliation
OnlyDedicatedMenuButtonsboolRequire dedicated menu buttons
ArcadeOptionsNavigationintArcade navigation mode

​
Audio & Timing

PreferenceTypeDescription
GlobalOffsetSecondsfloatGlobal timing offset in seconds

​
Content Generation

PreferenceTypeDescription
AutogenStepsboolAuto-generate steps
AutogenGroupCoursesboolAuto-generate group courses

​
Unlocks & Extras

PreferenceTypeDescription
UseUnlockSystemboolEnable unlock system
AllowMultipleToastiesboolAllow multiple toasty triggers
ShowSongOptionsenumShow song options screen

​
Setting Preferences via GameCommands

You can set preferences using the setpref GameCommand: 
"setpref,Windowed,1"
See GameCommands for more details.

​
Setting Preferences via Lua

Preferences can be accessed and modified through Lua: 
-- Get a preference
local windowed = PREFSMAN:GetPreference("Windowed")

-- Set a preference
PREFSMAN:SetPreference("Windowed", true)

-- Save preferences to disk
PREFSMAN:SavePreferences()

​
Theme Preferences

Themes can define their own preferences using the ThemePrefs system. These are stored separately in Save/ThemePrefs.ini.

​
Declaring Theme Preferences

local Prefs = {
  BoolPref = { Default = false },
  IntPref = { Default = 3 },
}

ThemePrefs.InitAll(Prefs)

​
Using Theme Preferences

-- Get a theme preference
local value = GetThemePref('BoolPref')

-- Set a theme preference
SetThemePref('BoolPref', true)
Theme preferences are theme-specific and stored under the theme’s name section in ThemePrefs.ini.

​
Command-Line Preference Override

Use the --Type argument to load preferences from alternate sections: 
stepmania --Type=arcade
This reads from [Preferences-arcade] instead of the default section.

​
Notes

  • Changes to most preferences require restarting StepMania
  • Display-related preferences take effect immediately in some cases
  • Preferences are automatically saved when modified through the options menu
  • Direct INI file edits require StepMania restart to take effect

Build docs developers (and LLMs) love

Get started for freeTalk to us