stepmania/stepmania — pull request #148 by kyzentun (2014-05-02 05:46:38+00:00)
Title: Player options fix

To silence fears about changing an existing API, the existing PlayerOptions API was not safe to use anyway. The only way to get a PlayerOptions object in Lua was to use PlayerState:GetPlayerOptions. PlayerState:GetPlayerOptions pushed a pointer to a temporary object that was immediately destroyed when the function returned. So anybody that tried to use it got a PlayerOptions that could not be used to set options, and returned garbage if it didn't seg fault.

This request fixes that by removing the const protection on the members of ModsGroup so that PlayerState:GetPlayerOptions can push the PlayerOptions objects that are actually in use. So now the PlayerOptions that is returned can be used to set the player's options at any ModsLevel. ModsLevel_Current is also now accessible through the enum.

The new Lua interface for PlayerOptions follows the paradigm of combining Get and Set into one function. The parameters for all the functions are optional and they store the value before setting it, returning the previous value. (so "prev_boost= options:Boost(5) options:Boost(prev_boost)" is a good way to change Boost and then change it back)
The new functions also give access to the approach speeds for the mods, following the same paradigm, and returning the approach speed as the second return value (so "value, approach= options:Boost()" is the way to get both)
Because the functions are almost all identical in usage, most of them are not individually documented. The few that are not identical to the general paradigm are individually documented. If they were to be individually documented, it would be with a short description of what each mod does and require a lot of research.
Speed mods are accessible both directly through setting the TimeSpacing, MaxScrollBPM, ScrollSpeed, ScrollBPM, and through the more familiarly named CMod, XMod, and MMod functions. The docs warn the themer that the direct functions shouldn't be used by the inexperienced.
Perspective mods are also accessible directly through setting Tilt and Skew and through the familiarly named functions, with a similar warning to speed mods.