StepMania 5 beta 4; release notes compiled by @kyzentun and Markdown formatted by @freem:
This is divided into three sections:
- Player visible changes: New configuration options players should try out,
- Themer visible changes: New (optional) screens that themes can support, new metrics or lua functions, or fixes for existing functions.
- Prominent bug fixes: Bugs that seem prominent and aren't solely relevant to themers.
Each section will first list each of the items in it, then after the full list, each item will be discussed in detail.
Items are roughly grouped into the general part of Stepmania they fit into.
Player visible changes
- Arbitrary Speed Mods
- Customize Profile
- Error Reporting
- CMods adjust for song rate.
- Lowercase and longer ranking names. (if theme supports it)
- New Swap Up/Down and Arbitrary Remap feature in Edit Mode
- Extra Stage: Default theme's speed mod changed to 2x.
New Preferences:
- BackgroundFitMode
- ComboContinuesBetweenSongs
- DebounceCoinInputTime
- DefaultFailType
- FastNoteRendering
- ThreeKeyNavigation
Specifics
Arbitrary Speed Mods
In the default theme, speed mods are set in a new way.
The first element on the speed mod row tells you what your speed mod is currently set to. Call this the status element. It's underlined by the player's color the same way any other option that is set is underlined.
Next are elements for adjusting it up or down, in large or small increments.
Last are elements for changing the mode of the speed mod.
Hit start on an element to interact with it and change your speed mod by that increment or change the mode. The status element will update to tell you the new setting.
If there are two players joined, there are two status elements.
To change the sizes of the increments, go to the Advanced Options section of the Options in the default theme. "Speed Increment" adjusts the smaller increment that is used. "Speed Increment Large" adjusts the larger increment. 10 on this scale is equivalent to 0.1x on the XMod scale.
This replaces the old system where a speed mod was selected from a small set to allow you to set any speed modifier you might want without needing to worry about whether it's in the theme's small list.
SpeedMods.txt is no longer used by the default theme, though other themes can choose to support it.
This change was made because editing SpeedMods.txt often resulted in people making mistakes or editing the wrong one, or not knowing it existed, or having to add too many options and ending up with an absurd number of choices to scroll through.
Customize Profile
A profile customization screen now exists. This is for setting things like weight, birth year, and other calorie tracking stuff. If you're not using a theme that supports it, it's not relevant. Theme author instructions for adding support are in the Themer section.
To reach it, go to the Options screen from the main menu. Then go to Profiles. Pick the profile you want to customize. A menu will appear. Pick Edit. You'll see a menu of choices. Hit Start on a choice to change its value. The numpad should be self-explanatory.
This screen was added to allow setting the profile settings related to calculating how many calories were burned. Simply put, calculating calories purely off the number of steps hit and weight is inaccurate, so a new method for calculating off of heart rate, weight, age, gender and song duration was added. (shapesense's formula is the one that was used.)
VO2Max is optional, the internal code has a (less accurate) variant of the formula that is used if VO2Max is set to 0.
If you set the calorie calculation choice to use heart rate, then calories will not be added to the profile for every step. If the theme supports it, a screen for entering your heart rate will come up after gameplay and before evaluation. It will have a timer so you can measure your pulse and a numpad for entering the BPM of your heart. After you enter your heart rate, it'll be combined with the time to calculate the number of calories to add to the profile.
Error Reporting
This is really more of a themer feature, but so many themes have errors in them that it's going to be widely seen.
Errors in themes are now reported in dialog boxes and on screen much more than they previously were. (this is in addition to the Logs/log.txt reporting that has existed much longer)
This means that if you use a theme with errors in it, you'll be interrupted by dialog boxes and text on the screen reporting the errors.
There isn't a way to turn error reporting off, and there are no plans to add a way to turn it off. The solution is to use a theme that doesn't have errors, or fix them if a theme you made has errors. If you're a themer and you encounter an error you don't know how to fix, ask for help on the stepmania forums.
CMods adjust for song rate. Previously, if you used a rate mod, you'd have to pick a different CMod from normal to account for the rate. The CMod code now checks the song rate mod and adjusts appropriately. The same is true of MMods. Haste is not adjusted for because the sudden changes that can occur from haste would cause the arrows to jump disorientingly.
Lowercase and longer ranking names. The internal functions for storing ranking names were modified to allow mixed case and longer length. This only matters if the theme allows mixed case and/or longer length input.
Swap Up/Down and Arbitrary Remap in Edit Mode
New options have been added to the Alter menu.
Swap Up/Down swaps the Up/Down columns in the selected region. In double, this swaps Up and Down on both pads. In Pump, this swaps the front and back panels (UL is swapped with DL, UR is swapped with DR).
Arbitrary Remap provides a way to swap columns around arbitrarily. You will be prompted to enter a comma separated string of column numbers. After the remapping, each column will have a copy of the notes from the column number you entered. So entering "2, 1, 4, 3" will move down to left, left to down, right to up, and up to right. "1, 1, 1, 1" will copy the notes from left to every column.
Extra Stage
Default theme's speed mod changed to 2x.
New Preferences
BackgroundFitMode
Background stretching has been a problem for a while, so now there's a preference for setting it. In the default theme, select "Set BG Fit Mode" from the Options menu to go to the screen for setting it. The screen will show the various choices, and how a background of each of the three common aspect ratios will be cut off by the screen edges.
Some themes are known to override the internal lua functions that provide this feature, and it will not work in those themes.
ComboContinuesBetweenSongs
A minor preference for having ITG's feature of accumulating a large combo across multiple songs. You'll have to find Save/Preferences.ini and set it to 1 in that file to enable it.
DebounceCoinInputTime
A minor preference to cover the rare case where an arcade machine needs a different debounce time for coin input. This must be set by editing Save/Preferences.ini. Specifically, this was added to cover a case where someone had a bill acceptor added to their machine that worked by sending multiple coin insert inputs very quickly.
DefaultFailType
Kind of an internal thing, but you'll have to re-set your Default Fail Type preference.
FastNoteRendering
A minor preference for making note rendering faster. If you notice that your frame rate is low during very dense streams, you'll want to turn this on. It can be set in the Graphics/Sound section of the Options. The downside is that 3D notes will clip into each other instead of later notes being drawn on top of earlier notes.
ThreeKeyNavigation
A minor option for cabinets that only have Left, Right, and Start buttons. This can be set in the Input Options section. This forces the player options screen to have a down element for each row, so the cursor can no longer get stuck on rows that have multiple selections possible.
Themer visible changes
New stuff added to Docs/Themerdocs.
Metrics are marked with [M].
Functions are marked with [F].
Attributes (things you set inside the lua file when creating the actor with Def.whatever) are marked with [A].
Bug fixes are marked with [B].
If a function is explained sufficiently by its entry in Docs/Luadoc/Lua.xml, it won't have a detailed entry.
Actor
- [F] GetDestX/Y/Z
- [F] texturetranslate
Actor Classes
- ActorMultiVertex
- LogDisplay
- NumPadEntry
ActorFrame
- [B] diffuse/glow applied to BitmapText children
- [F] GetChild, GetChildren improved
ActorScroller
- [A] LoopScroller
- [A] WrapScroller
- DrawByZPosition fixed for looping.
BitmapText
- [F] distort
- [F] max_dimension_use_zoom
- [A] Font (LoadFont obsoleted)
Classes/Namespaces
- ArrowEffects
- PlayerOptions
- SongOptions
- TapNote
ComboGraph
- [M] BodyHeight
Common Metrics
- [M] AfterThemeChangeScreen, AfterGameChangeScreen, AfterGameAndThemeChangeScreen
GameManager
- [F] SetGame
GameSoundManager
- [F] IsTimingDelayed
- [F] PlayMusicPart
- [F] StopMusic
GameState
- [F] GetCurrentStage
- [F] GetLastGameplayDuration
- [F] GetStylesForGame
- [F] HaveProfileToLoad/Save
- [F] InsertCoin and InsertCredit
- [F] JoinInput
- [F] Load/SaveProfiles
- [F] SetCurrentPlayMode
- [F] SetCurrentStyle
- [F] StoreRankingName
Global functions
- [F] GetTimeSinceStart
- [F] OldStyleStringToDifficulty
- [F] SaveScreenshot
Judgment message
- Notes and Holds parameters
- HoldNoteScore_MissedHold
LifeMeter
- LifeType, DrainType, BatteryLives
- LifeMeterChanged message
LifeMeterBattery
- [M] CourseSongRewardLives
MusicWheel
- [F] GetSelectedSection
NoteSkinManager
- [F] GetMetric, GetMetricForNoteSkin
PlayerStageStats
- [F] GetComboList, GetLifeRecord
PrefsManager
- [F] SavePreferences
Profile
- Heart rate stuff
- [F] SetLastUsedHighScoreName
- [F] GetHighScoreListIfExists
RageTexture
- [F] Reload
Screen
- [F] SetNextScreenName
- [F] AddInputCallback and RemoveInputCallback
Screens
- ScreenContinue
- ScreenCredits
- ScreenHeartEntry
- ScreenOptionsCustomizeProfile
- ScreenMapControllers
- ScreenSetBGFit
ScreenGameplay
- Themable haste system.
- [F] GetHasteRate
- [F] GetTrueBPS
ScreenHowToPlay
- [M] CharacterName metric fixed.
ScreenSelectMusic
- SelectMenuInput message
ScreenWithMenuElements
- [F] SetAllowLateJoin
- [F] StartTransitioningScreen
Sprite
- [F] SetCustomPosCoords
Style
- [F] GetColumnInfo, GetColumnDrawOrder
ThemeManager
- [F] GetMetricNamesInGroup, GetStringNamesInGroup
- [B] HasMetric/HasString return false for empty string
- [F] SetTheme
TimingData
- [M] GetReturnsNumbers
WheelItemBase
- [F] IsLoaded
Details
Docs/Themerdocs/Examples (and other new Themerdocs stuff)
A few examples of basic things and some advanced things now exist. Any questions for clarifying examples are welcome.
Actor Classes
ActorMultiVertex
A new actor class for arbitrarily shaped actors.
Detailed documentation is Docs/Themerdocs/ScreenAMVTest overlay.lua
LogDisplay
A new actor class for displaying a log of messages. This is what Error Reporting uses internally for displaying the errors on screen, so if you want to have a log of something on screen in your theme, it's provided for general use. _fallback/Scripts/04 LogDisplay.lua discusses its customizable features in detail.
NumPadEntry
A new actor class for displaying an interactive numpad for entering a number. This is used by ScreenHeartEntry and ScreenOptionsCustomizeProfile for entering numbers, so you'll want to read up on it when working on those screens for your theme. _fallback/Scripts/04 NumPadEntry.lua discusses it in detail, and default/BGAnimations/ScreenHeartEntry overlay.lua has an example of it in use. (NumPadEntry.lua mentions an example that doesn't actually exist yet. It seemed superfluous to create an example after having such detail in the file already)
ActorFrame
[F] GetChild, GetChildren improved
Some themers may have known this already, some may not. If multiple actors inside an ActorFrame have the same name, GetChild would only return the first one, and GetChildren would only have one Actor by that name in the table it returns. This was particularly a problem when dealing with actors from the engine, where you can't control the name. GetChild and GetChildren were modified to return a table of all the actors by that name instead of just the single actor. The table does some fancy work to make old code that treats it as a single actor still work, but you probably want to update your code to take advantage of being able to access the individual actors anyway.
BitmapText
[A] Font (LoadFont obsoleted)
BitmapText will now automatically apply THEME:GetPathF to the Font attribute if it's not already the path to a valid font, so LoadFont is obsolete.
Example: Def.BitmapText{ Font= "Common Normal", Text= "Example" }
Classes / Namespaces
ArrowEffects
A namespace full of functions for advanced themers that want to reimplement the entire notefield in Lua. See Lua.xml for function list.
PlayerOptions
A class of functions for getting and setting the options (also called modifiers) for a player. This is a replacement for using GetPlayerOptionString/Array for fetching the player's options and a replacement for using ApplyGameCommand to set the player's options. It's intended to be used by scripted simfiles that want to use numbers instead of strings, and advanced themes that want to offer more powerful options screens. Lua.xml lists the functions and their usage. Themerdocs/modslevel.txt discusses which ModsLevel should be passed to PlayerState:GetPlayerOptions for the different uses.
SongOptions
Same as PlayerOptions, but for the song modifiers, like the music rate. Fetch with GAMESTATE:GetSongOptionsObject.
TapNote
Minor class for storing the data passed in new JudgmentMessage parameters. Functions are listed in Lua.xml. Note that the TapNotes only exist for the duration of the song, so an data in them that is needed should be copied by calling their functions and storing what the functions return. This is for use by advanced themes that have some reason for tracking more judgment data than the engine tracks.
Common Metrics
[M] AfterThemeChangeScreen, AfterGameChangeScreen, AfterGameAndThemeChangeScreen:
Theme and game changing logic was changed a bit internally. These metrics are optional. When the theme or game changes, Stepmania will check the appropriate metric and load that screen after the change. If the metric is not set, the InitialScreen metric is used instead.
GameState
[F] GetCurrentStage: You probably have some kludgy way of detecting whether the current stage is Stage_Final somewhere in your theme because GetCurrentStage wasn't returning the right thing when on gameplay. That's been fixed, so you can use GetCurrentStage without worrying now.
[F] GetLastGameplayDuration: This is useful for implementing heart rate based calorie calculation support in your theme. Call this function on your ScreenHeartEntry to get the length of time to pass to Profile:CalculateCaloriesFromHeartRate.
Judgment message
Notes and Holds parameters: When a note is hit and the "Judgment" message is broadcast, it has two new parameters. Notes is a table of all the TapNotes on that row. Holds is a table of all the TapNotes that are holds on that row. This can be used to check more detailed judging data when handling the Judgment message.
HoldNoteScore_MissedHold: HoldNoteScore_MissedHold is a new HoldNoteScore for when a hold is missed entirely because the player didn't hit the note at the start of the hold.
LifeMeter
LifeType, DrainType, BatteryLives
LifeType, DrainType, and BatteryLives used to be modifiers applied to the song, and both players were forced to use the same values. They have been moved to player options, so now they can be set to different values for each player.
LifeMeterChanged message
The LifeMeterChanged message had a bug that causes LifeMeterChangedP1 to be broadcast for both players. This has been fixed so LifeMeterChangedP1 is broadcast for Player 1, and LifeMeterChangedP2 is broadcast for Player 2. The params table for LifeMeterChanged contains two values: Life for the value the life meter was changed to, and StepsSecond, for the time the change occurred.
LifeMeterBattery
[M] CourseSongRewardLives: Metric used to reward the player with battery lives after every song in a course. This metric must be set to a function. The function is passed the LifeMeterBattery for the player, and the PlayerNumber. It must return a number, which can be any amount, but the lives left will be capped by the player's BatteryLives option. _fallback/metrics.ini has a simple example.
MusicWheel
[F] GetSelectedSection: A replacement for whatever crude kludge you're using to get the text of the current music wheel item.
Profile
Themerdocs/calories.txt lists the new functions for setting the parts of the profile related to calorie calculation.
Screens
ScreenCredits
The credits screen has been modified a bit internally to make it easier to add sections with custom theme credits without removing the main Stepmania credits.
ScreenHeartEntry
With a new way of calculating the number of calories burned, comes a new way for entering the information it needs.
This screen appears after gameplay and before evaluation, but only if at least one of the players has it enabled and the theme supports it.
See Themerdocs/Examples/Example_Screens/ScreenHeartEntry.lua for an in-depth example.
ScreenOptionsCustomizeProfile
(todo)
ScreenMapControllers
At a minimum, you want to set the LinesVisible metric to the correct value for your theme so that ScreenMapControllers knows when to stop scrolling the rows so the player's cursor can't go off the screen.
Themerdocs/Examples/Example_Screens/ScreenMapControllers.lua discusses the themable parts of ScreenMapControllers.
ScreenSetBGFit
This is the screen for presenting the BackgroundFitMode preference so the player knows exactly how their choice will affect backgrounds by looking at the effect each choice has on an image of each of the common aspect ratios. _fallback/BGAnimations/ScreenSetBGFit overlay.lua is a detailed example.
ScreenGameplay
Themable haste system: Themerdocs/haste.txt discusses changing the way the haste system behaves if you want your theme to have different haste behavior from the default.
ScreenSelectMusic
SelectMenuInput message: Previously, if the SelectMenuChangesDifficulty metric was true, the SelectMenuInput message would not be broadcast for button presses with select held down. Now the message is always broadcast for button presses while select is held down.
TimingData
[M] GetReturnsNumbers: TimingData contains all the timing data for a Steps, and has functions for fetching it so the theme can see what the timing data was. Previously, these functions would all return strings and the theme would have to parse the strings to turn them into numbers befor it could do anything useful. Now, if the TimingData::GetReturnsNumbers metric is set to true, the TimingData functions will return numbers instead of strings.
Bug fixes
- Endless mode loop crash/repick songs: Repeating courses now repick randomized songs when they repeat and no longer crash on evaluation.
- Harmful pad codes disabled: No more accidentally turning on drunk.