StepMania Creators' Guide

Development documentation for creating StepMania content such as themes.

Front matter

Front matter


©2019-present StepMania Development Team, Team Rizu and contributors

Except where otherwise noted, this manual is licensed under the Creative Commons Attribution 4.0 International License. Source code and other code content from StepMania itself is licensed under the MIT License.

Lua documentation

Lua documentation

Lua Documentation: Global Functions


Global Functions

Alpha (  color cfloat percent ) [return color]


Returns a color with the specified Alpha.

approach float current, float goal, float speed ) [return float]

Use this to make a current value approach a goal value at the given speed. Speed must not be negative. The value will not overshoot the goal.

When you see the error "approach: speed 1 is negative." it means that the speed value passed was negative. The 1 is there because approach and multiapproach use the same internal function and can be ignored when using approach.

ArbitrarySpeedMods [return LuaOptionRow]

This is the lua based Speed Mod system currently found in Themes/_fallback/03 customspeedmods.lua. Does not take any kind of parameters when inserted into a screen, as it grabs from preferences usually located in Advanced Options to set the margin of your selections when choosing a speed mod.


PlayerOptions and Modifiers

PlayerOptions and Modifiers

Scripting Modifiers

StepMania's PlayerOptions are used for many of the settings found on the pre-song options menus, including note display speeds, NoteSkins, direction, and other effects. They are usually selected manually by the player, but they can also be scripted and choreographed to provide an additional challenge for players.

This has been achieved through several means.

  • .CRS files are used to define courses for the Nonstop/Marathon modes. Using markup in the file, a course writer can configure certain mods to be activated at specific times or beats in a song when played during the course. This method was used for the Marathon/Progressive courses In the Groove and Pump it Up Pro franchises.
  • #ATTACKS provides a means for embedding .CRS-style modifier attacks within a song's .ssc file.  The user can enable or disable these attacks in the options menu.
  • The majority of current "mod files" (including works by TaroNuke, WinDEU, and others) typically use Lua templates that are loaded via FGChanges (a foreground layer that is part of the BGChanges system for visuals and music videos during songs).
    • These templates typically use a series of tables to store modifier combinations (often in a somewhat similar syntax to .crs files), although they are accompanied by functions and scripting that allow for finer control, and for manipulating and tweening the notefields themselves as an actor for more complex effects. Due to the nature of some of these effects, these files often require Versus/2-player mode to render correctly.
    • Mod files may sometimes use other advanced StepMania graphics features for visual effects, such as ActorFrameTexture. Templates may include a message system for triggering commands on other actors.
PlayerOptions and Modifiers

List of modifiers

Introduced in StepMania 5.1

  • Column specific modifiers, where N is the column number. Column numbers begin at 1 (note that in NotITG, column numbering for these modifiers begin at 0)BumpyN
    • DarkN
    • ConfusionOffsetN
    • ConfusionXOffsetN
    • ConfusionYOffsetN
    • Move note columns (100% in one direction is equivalent to ARROW_SIZE)
      • MoveXN
      • MoveYN
      • MoveZN
    • ReverseN
    • TinyN
  • Tangent-based modifiers
    • tanBumpy
    • tanBumpyX
    • tanDigital
    • tanDigitalZ
    • tanDrunk
    • tanDrunkZ
    • tanExpand
    • tanTipsy
    • tanTornado
    • tanTornadoZ
    • Cosecant (When set to true, tangent modifiers use cosecant waves instead, based on the tangent modifier behavior on NotITG V1)
  • Attenuate
    • AttenuateX
    • AttenuateY
    • AttenuateZ 
  • Beat
    • BeatOffset (50% causes beats to occur on 8th notes)
    • BeatPeriod (waveform length of the beat mod at peak wave amplitude)
    • BeatMult (multiplies the BPMof the beat effect)
    • BeatY
    • BeatYOffset
    • BeatYPeriod
    • BeatYMult
    • BeatZ (Beat's effect applied to the z position)
    • BeatZOffset
    • BeatZPeriod
    • BeatZMult
  • Bounce
    • Bounce - uses absolute value of a sine function
    • BouncePeriod
    • BounceOffset
    • BounceZ - Bounce's effect on the z position
    • BounceZPeriod
    • BounceZOffset
  • Bumpy
    • BumpyOffset
    • BumpyPeriod
    • BumpyX (Bumpy's effect applied to the x position)
    • BumpyXPeriod
    • BumpyXOffset
  • Confusion
    • ConfusionOffset (Rotates both notes and receptors by a given amount on the z axis, and keeps them there)
    • ConfusionX (Confusion on the X axis instead of Z)
      • ConfusionXOffset
    • ConfusionY (Confusion on the Y axis instead of Z)
      • ConfusionYOffset
  • Digital (Arrow path takes the form of a digital sine wave)
    • DigitalSteps (more steps means a smoother wave)
    • DigitalPeriod
    • DigitalOffset
    • DigitalZ (Digital's effect applied to the z position)
    • DigitalZSteps
    • DigitalZPeriod
    • DigitalZOffset
  • DizzyHolds (When set to true, hold heads become affected by Dizzy. Replaces the DizzyHoldHeads metric)
  • DrawSize (affects how far down the notefield renders the notes; 100% = double, -50% = half)
  • DrawSizeBack (affects how far the notefield renders notes after the receptors; 100% = double, -50% = half)
  • Drunk
    • DrunkSpeed
    • DrunkOffset
    • DrunkPeriod (change the period of the oscillations of drunk)
    • DrunkZ (Drunk's effect applied to the z position)
    • DrunkZSpeed
    • DrunkZOffset
    • DrunkZPeriod
  • Expand
    • ExpandPeriod
  • Parabola
    • ParabolaX (Arrow path takes the form of a parabola in the x position)
    • ParabolaY (Arrow path takes the form of a parabola in the y position)
    • ParabolaX (Arrow path takes the form of a parabola in the z position)
  • PulseInner
  • PulseOuter
  • PulsePeriod
  • PulseOffset
  • Sawtooth (Arrow path takes the form of a sawtooth wave)
    • SawtoothPeriod
    • SawtoothZ (Sawtooth's effect applied to the z position)
    • SawtoothZPeriod
  • ShrinkLinear
  • ShrinkMult
  • Square (Arrow path takes the form of a square wave)
    • SquarePeriod
    • SquareOffset
    • SquareZ (Square's effect applied to the z position)
    • SquareZPeriod
    • SquareZOffset
  • StealthPastReceptors (When set to true, Stealth and similar effects persist for notes that go past the receptors. Replaces the DrawHiddenNotesAfterReceptor metric)
  • StealthType (When set to true, Stealth and similar effects are based off of YOffset instead of YPosWithoutReverse. Mainly affects modifiers like BeatY and other similar mods that work on the y position)
  • Tipsy
    • TipsySpeed
    • TipsyOffset
  • Tornado
    • TornadoPeriod (control the helix length)
    • TornadoOffset (control how far into the tornado the receptors are) (100% = +1)
    • TornadoY
    • TornadoZ
    • TornadoZ (Tornado's effect applied to the z position)
    • TornadoZPeriod
    • TornadoZOffset
  • WavePeriod (Control the wave length)
  • Zigzag (Arrow path takes the form of a triangle wave)
    • ZigzagPeriod
    • ZigzagOffset
    • ZigzagZ (Zigzag's effect applied to the z position)
    • ZigzagZPeriod
    • ZigzagZOffset
  • ZBuffer (When set to true, turns on the zbuffer. Useful for when zbuffer is wanted without needing to turn on effects like 0.5% bumpy.)

Introduced in StepMania 5.3