diff --git a/Docs/Luadoc/Lua.xml b/Docs/Luadoc/Lua.xml index bec2e01f46..3e3415f4ef 100644 --- a/Docs/Luadoc/Lua.xml +++ b/Docs/Luadoc/Lua.xml @@ -9,6 +9,8 @@ + + @@ -24,6 +26,11 @@ + + + + + @@ -42,11 +49,13 @@ - + + + @@ -55,6 +64,7 @@ + @@ -63,6 +73,7 @@ + @@ -87,6 +98,7 @@ + @@ -118,12 +130,14 @@ + + @@ -137,7 +151,6 @@ - @@ -146,7 +159,10 @@ + + + @@ -158,18 +174,13 @@ - - - - - - + @@ -190,9 +201,9 @@ + - @@ -203,25 +214,33 @@ + + + + + + + + + + - - @@ -230,23 +249,29 @@ + + + + + + @@ -254,12 +279,18 @@ + + + + + + @@ -752,6 +783,8 @@ + + @@ -1013,6 +1046,8 @@ + + @@ -1503,6 +1538,8 @@ + + @@ -1839,6 +1876,8 @@ + + @@ -2330,6 +2369,18 @@ + + + + + + + + + + + + @@ -2930,6 +2981,6 @@ - StepMania5.1-git-d03ec2658f - 2020-05-11 + StepMania5.1-git-89229ed915 + 2020-06-25 diff --git a/Docs/Luadoc/Lua.xsd b/Docs/Luadoc/Lua.xsd index 3edd27c34f..7b5954af5b 100644 --- a/Docs/Luadoc/Lua.xsd +++ b/Docs/Luadoc/Lua.xsd @@ -89,6 +89,7 @@ + diff --git a/Docs/Luadoc/Lua.xsl b/Docs/Luadoc/Lua.xsl index 64986a12d7..b655c3a95e 100644 --- a/Docs/Luadoc/Lua.xsl +++ b/Docs/Luadoc/Lua.xsl @@ -106,7 +106,7 @@ font-family: monospace; } .descriptionText { - text-indent: 2em; + padding-left: 2em; margin-top: 0; margin-bottom: 0; } @@ -169,7 +169,7 @@ var listid = 'list_' + id; var img = document.getElementById( imgid ); var list = document.getElementById( listid ); - + img.setAttribute( 'src', 'open.gif' ); list.style.display = 'block'; } @@ -184,7 +184,7 @@ var listid = 'list_' + id; var img = document.getElementById( imgid ); var list = document.getElementById( listid ); - + if( img.getAttribute('src') == 'closed.gif' ) { img.setAttribute( 'src', 'open.gif' ); @@ -200,7 +200,7 @@ - + \ @@ -648,7 +648,7 @@ - + @@ -670,6 +670,14 @@ + + + 
+		
+			
+		
+
+
diff --git a/Docs/Luadoc/LuaDocumentation.xml b/Docs/Luadoc/LuaDocumentation.xml index 765ecc3aaa..46e085c629 100644 --- a/Docs/Luadoc/LuaDocumentation.xml +++ b/Docs/Luadoc/LuaDocumentation.xml @@ -28,30 +28,54 @@ save yourself some time, copy this for undocumented things: + + Many global functions are available when scripting with Lua for StepMania.
+ Some, like , are core functions of Lua 5.1's basic Library.
+ Others, like , are defined in the StepMania engine's C++ but made available to Lua.
+ And others, like , are defined in the _fallback theme's Lua files.
+ When scripting with StepMania, keep in mind that if you do not scope your functions (and variables) using the local keyword, they will be global. + + + [03 Gameplay.lua] Returns false if the player should be disallowed from entering the options menu from ScreenSelectMusic (i.e. during an ExtraStage or when the is Oni). Returns true otherwise. + - [02 Colors.lua] Returns a color with the specified alpha. + [02 Colors.lua] Returns a color with HSV values matching c and alpha set to percent, where percent is in the range 0..1. 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.
Note: 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. - [03 CustomSpeedMods.lua] + [03 CustomSpeedMods.lua] Returns an of speed mod choices generated from the comma-delimited list in SpeedMods.txt in the root of the current Profile directory (player if available, machine otherwise). - [02 StageMods.lua] + [02 StageMods.lua] Returns true if player modifiers should be forced. This is effectively the negation of . - [02 StageMods.lua] + [02 StageMods.lua] Returns true if song modifiers should be forced (i.e. during an ExtraStage, or when the is Oni, Battle, or Rave). - Issues an error when v is false (or nil). Returns all arguments otherwise. sAssertMessage is an optional error message (the default is "assertion failed!"). + Issues an error when v is false (or nil). Returns all arguments otherwise. sAssertMessage is an optional error message (the default is "assertion failed!").
+ assert is a core function of Lua's basic library; see the Lua manual for more details. + + + [02 Utilities.lua] Returns two results.
+ If P1 is joined, the first return value will be arg1, and nil otherwise.
+ If P2 is joined, the second return value will be arg2, and nil otherwise. + + + [04 SetBGFitHelpers.lua] Returns an ActorFrame containing examples of how a given background image (with set aspect ratio) will appear in a particular .
+ The _fallback theme uses this to visually represent choices for ScreenSetBGFit, intended to help players choose a BackgroundFitMode preference. + + + [04 SetBGFitHelpers.lua] Returns an ActorFrame with an InputCallback attached.
+ The _fallback theme uses this to manage input on ScreenSetBGFit, intended to help players choose a preference. - Returns the base name of file path. + Returns the last named component of path. For example, passing in "/path/to/file.txt" will return "file.txt", while "/path/to/some/directory/" will return "directory". - [02 Colors.lua] Boosts the specified color by multiplying its values by fBoost. + [02 Colors.lua] Returns the color that results from multiplying c's R, G, and B values by fBoost. [02 Colors.lua] Modifies the brightness of the specified color. @@ -71,7 +95,8 @@ save yourself some time, copy this for undocumented things: Closes any connection to an online server. - A generic interface to Lua's garbage collector. Performs different functions based on the value of opt. + A generic interface to Lua's garbage collector. Performs different functions based on the value of opt.
+ collectgarbage is a core function of Lua's basic library; see the Lua manual for more details. Returns a color from a string. color can be in hex ("#FFFFFFFF") or 0..1 values ("1.0,1.0,1.0,1.0"), in RGBA order. @@ -86,10 +111,10 @@ save yourself some time, copy this for undocumented things: [02 Colors.lua] Returns a midtone of the color. (Specifically c[1]/1.5, c[2]/1.5, c[3]/1.5, c[4]) - [02 Colors.lua] Returns a hex representation for the specified color. + [02 Colors.lua] Accepts a color and returns the hex representation. For example, passing in {1, 0, 0.4, 1} will return "FF0066FF". - [02 Colors.lua] Takes in a color and returns a table with the HSV values. + [02 Colors.lua] Accepts a color and returns a table with the HSV values, indexed by Hue, Sat, Value, and Alpha. [03 Gameplay.lua] Determines what TapNoteScore allows for continuing the combo. @@ -101,10 +126,8 @@ save yourself some time, copy this for undocumented things: [03 Gameplay.lua] Determines if combo should be per row (Jump = 1) or per column (Jump = 2). - [02 Other.lua] The combo trasform command. - - - [03 Gameplay.lua] Returns the UserPrefComboUnderField user preference value. + [02 Other.lua] Defines the transform function used to position player combo during gameplay. params will contain two boolean values indexed by bReverse and bCentered.
+ Not intended to be called directly by themes. This will take the number and insert a comma every three digits, as normal in English for writing large numbers.
@@ -118,10 +141,18 @@ save yourself some time, copy this for undocumented things: Tries to connect to the server at sAddress. + + Returns d localized for the current language using strings defined under [CourseDifficulty]. + + + Returns ct localized for the current language using strings defined under [CourseType]. + + + [02 Utilities.lua] Utillity function used to format log output for presenting on-screen. indent is the number of pixels to indent lines. width is the width in pixels that lines should be constrained to. + - Recursively searches dir for xml files of actors and - converts them to equivalent lua files. See Docs/Themerdocs/XmlToLua.txt - for details. + Recursively searches dir for xml files of actors and converts them to equivalent lua files. + See Docs/Themerdocs/XmlToLua.txt. Creates a RageBezier2D for you to use. Make sure you destroy the RageBezier2D when you're done with it, or you will have a memory leak. @@ -138,17 +169,21 @@ save yourself some time, copy this for undocumented things: [02 Colors.lua] + + Returns cd localized for the current language using strings defined under [CustomDifficulty]. + - Returns the current day of the month. + Returns the current day of the month in the range 1-31. - Returns the current day of the year. + Returns the current day of the year in the range 0-365. [02 Serialize] Recursively deep-copy a table. - [01 base.lua] "Override Lua's dofile to use our loadfile." + dofile is normally a core function of Lua's basic library. StepMania overrides this in + [01 base.lua] to use loadfile, which itself has been overridden. [03 Gameplay.lua] @@ -162,8 +197,8 @@ save yourself some time, copy this for undocumented things: This function creates files in the theme's Languages folder listing all the strings that have no translation and all the strings that are unused.
Strings that do not have an entry in the master language are considered unused.
- master_lang_name is the name of the ini file that contains the language with all strings used by the theme.
- Example: find_missing_strings_in_theme_translations("my_best_theme", "en.ini") + master_lang_name is the name of the ini file that contains the language with all strings used by the theme.
+ Example: find_missing_strings_in_theme_translations( "my_best_theme", "en.ini" ) [02 Utilities.lua] Return the index of a true value in list. @@ -172,12 +207,16 @@ save yourself some time, copy this for undocumented things: [02 Utilities.lua] Find a key in tab with the given value. - func takes a key and a value. + f takes a key and a value. + + Returns the number passed to the function followed by its suffix ("th", "nd", and so on). - + + [02 Other.lua] Concatenates num with " songs played" and returns the resulting string. + Returns fPercentDancePoints formatted as a percentage. @@ -187,6 +226,10 @@ save yourself some time, copy this for undocumented things: [03 Gameplay.lua] + + [02 Other.lua] Returns the value of the CoursesToShowRanking preference if it is not an empty string.
+ Otherwise, returns a comma-delimited set of paths to the .crs files included with StepMania as a string. This string is hardcoded and does not accurately reflect whether those crs files exist in the filesystem. + Returns the corresponding CustomDifficulty string for a StepsType/Difficulty (/optional CourseType) combination. @@ -206,23 +249,20 @@ save yourself some time, copy this for undocumented things: Returns a corresponding for the given percentage. - Returns the current Life Difficulty. + Returns the current Life difficulty in the range of 1-7 - Returns the length of the music file found at path.
- If you are loading the sound into an ActorSound, ActorSound:get to get its RageSound then use RageSound's get_length function instead to avoid loading the file twice. + Returns the length of the music file found at path in seconds.
+ If the file has already been loaded into an ActorSound, use to get its RageSound, and then use to avoid loading the file twice. - Returns a table of the names of the sound drivers available. If the SoundDriver preference is set to something that is not in this list, StepMania WILL NOT START UP. Changes to the SoundDriver preference do not take effect until the next time StepMania starts up. - - - Returns a string representing the name of the operating system being used. (e.g. "Windows", "Linux", "Mac, "Unknown") + Returns a table of the names of the sound drivers available. If the SoundDriver preference is set to something that is not in this list, StepMania will not start up. Changes to the SoundDriver preference do not take effect until the next time StepMania starts up. [02 Utilities.lua] "This returns a profile, preferably a player one. If there isn't one, [it falls] back on the machine profile." - [03 ThemePrefs.lua] Returns true if player pn is using ProTiming. + [03 ThemePrefs.lua] Returns true if player pn is using the ProTiming UserPref. [02 Utilities.lua] Returns a path to a random song background. @@ -234,7 +274,7 @@ save yourself some time, copy this for undocumented things: [02 Actor.lua] - Returns the display aspect ratio. + Returns the screen display aspect ratio (i.e. the DisplayAspectRatio preference). Returns the name of the currently connected server. @@ -242,17 +282,21 @@ save yourself some time, copy this for undocumented things: [02 Utilities.lua] Returns a path to the current songs background. - + [03 Gameplay.lua] + + [03 CustomSpeedMods.lua] + - Returns the theme's aspect ratio. + Returns the theme's aspect ratio.
+ Specifically, this is the result of dividing ScreenWidth by ScreenHeight as each is defined under the theme's [Common] metric. - [03 ThemePrefs.lua] (Alias for .) + [03 ThemePrefs.lua] Alias for . - Returns the current Timing difficulty. + Returns the current Timing difficulty in the range of 1-9. Returns the current time since the program was started. Includes time that was spent loading songs. @@ -288,24 +332,28 @@ save yourself some time, copy this for undocumented things: [03 Gameplay.lua] Returns true if you need to step on hold heads to activate them. - [03 Gameplay.lua] Returns 0 in pump mode, TimingWindowSecondsHold preference value in any other game mode. + [03 Gameplay.lua] Returns 0 when the current is pump. Returns the TimingWindowSecondsHold preference value in other games. Returns the current hour. - - [02 Colors.lua] Converts a color from HSV values to something StepMania can understand. - hue is from 0-360, saturation and value are 0..1 + + [02 Colors.lua] Converts a color from HSV values to something StepMania can understand.
+ hue is from 0-360
+ saturation and value are 0..1 - - [02 Colors.lua] Converts a color from HSV values with alpha to something StepMania can understand. - hue is from 0-360, saturation, value, and alpha are 0..1 + + [02 Colors.lua] Converts a color from HSV values with alpha to something StepMania can understand.
+ hue is from 0-360
+ saturation, value, and alpha are 0..1 - [02 Colors.lua] "Converts a set of HSV values to a color." + [02 Colors.lua] Converts a table of HSV values to a color.
+ The hsv table should use indexes Hue, Sat, Value, Alpha. - [02 Colors.lua] "Takes in a normal color and returns the hex representation. (Adapted from code in LuaBit)" + [02 Colors.lua] Accepts a table of HSV values and returns the hex representation. + The hsv table should use indexes Hue, Sat, Value, Alpha. [02 Colors.lua] Changes the hue of the input color. @@ -313,17 +361,21 @@ save yourself some time, copy this for undocumented things: [03 ThemePrefs.lua] Initializes various user preferences. - - [01 base.lua] "Like ipairs(), but returns only values." + + Returns three values: an iterator function, the table t, and 0, + so that the construction for i,v in ipairs(t) do body end + will iterate over the pairs (1,t[1]), (2,t[2]), ···, up to the first integer key absent from the table.
+ ipairs is a core function of Lua's basic library; see the Lua manual for more details. [02 Utilities.lua] Returns true if the coin mode is not set to CoinMode_Home. - - Returns true if Event Mode is turned on. + + Returns true if the current is Nonstop, Oni, or Endless.
+ This is effectively the same as . - [02 Utilities.lua] Returns true if Arcade and the coin mode is CoinMode_Free. + [02 Utilities.lua] Returns true if IsArcade() and the coin mode is CoinMode_Free. [03 Gameplay.lua] Returns true if the current game is sGame. @@ -358,6 +410,9 @@ save yourself some time, copy this for undocumented things: [02 Colors.lua] + + Returns jl localized for the current language using strings defined under [JudgmentLine]. + [02 Colors.lua] @@ -365,7 +420,7 @@ save yourself some time, copy this for undocumented things: Returns a number linearly interpolated between start and end by percent. - Same as lerp, but for colors. All channels will reach the end of the interpolation at the same time. + Same as , but for colors. All channels will reach the end of the interpolation at the same time. Returns an Actor definition for the actor at sPath. If sPath points to a Lua file, any additional arguments will be passed to that script. @@ -377,7 +432,8 @@ save yourself some time, copy this for undocumented things: [02 ActorDef.lua] Loads an actor with params. - [01 base.lua] "Override Lua's loadfile to use lua.ReadFile." + loadfile is normally a core function of Lua's basic library. StepMania overrides this in + [01 base.lua] to use lua.ReadFile. [02 ActorDef.lua] Load the fallback BGA for the element that is currently being loaded. @@ -388,6 +444,9 @@ save yourself some time, copy this for undocumented things: [02 Sprite.lua] Returns a Sprite with the current song's background. + + Iterates over all functions exposed to Lua in class, creating CamelCase aliases for each function. Not intended to be used by themers. + Returns the length of the multi-byte character string sString. @@ -398,16 +457,17 @@ save yourself some time, copy this for undocumented things: [03 Gameplay.lua] Returns the value to start showing the miss combo at. - Creates a module. See the Lua manual for more details. + Creates a module.
+ module is a core function of Lua's basic library; see the Lua manual for more details. - Returns the current month of the year (0-11). + Returns the current month of the year in the range 0-11. - Returns Month m as a localized string. + Returns m localized for the current language using strings defined under [Month]. - Returns Month m as a string. + Returns m as a non-localized string. Similar to approach, but operates on tables of values instead of single values. This will modify the contents of currents in place, as well as returning currents.
@@ -416,10 +476,10 @@ save yourself some time, copy this for undocumented things: Note: When you see the error "approach: speed 1 is negative." it means that a speed value passed was negative. The 1 tells you which entry in the table was invalid. - "Allows a program to traverse all fields of a table. Its first argument is a + Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. - next returns the next index of the table and its associated value." - See the Lua manual for more details. + next returns the next index of the table and its associated value.
+ next is a core function of Lua's basic library; see the Lua manual for more details. Converts a string such as 'oni' or 'expert' or 'trick' to the appropriate difficulty. @@ -427,10 +487,12 @@ save yourself some time, copy this for undocumented things: [03 ThemePrefs.lua] Returns a Lua option row for ProTiming. + - "Returns three values: the function, the table t, and nil, + Returns three values: the function, the table t, and nil, so that the construction for k,v in pairs(t) do body end - will iterate over all key–value pairs of table t." + will iterate over all key–value pairs of table t.
+ pairs is a core function of Lua's basic library; see the Lua manual for more details. [02 Colors.lua] @@ -438,6 +500,15 @@ save yourself some time, copy this for undocumented things: [02 Colors.lua] + + Returns pma localized for the current language using strings defined under [PeakComboAward]. + + + Returns pm localized for the current language using strings defined under [PlayMode]. + + + Returns pn localized for the current language using strings defined under [PlayerNumber]. + [02 Utilities.lua] Converts a PlayerNumber into a short string (e.g. "P1", "P2"). @@ -448,10 +519,10 @@ save yourself some time, copy this for undocumented things: Returns a formatted percent with the specified numerator and denominator. - [00 init.lua] + [00 init.lua] Alias for . - [03 ThemePrefs.lua] Prints a table's contents to the log. + [03 ThemePrefs.lua] Prints a table's contents to log.txt using . Returns the product family. (e.g. "StepMania") @@ -460,17 +531,23 @@ save yourself some time, copy this for undocumented things: Returns the product ID. (e.g. "StepMania 5") - Returns the product version. + Returns the product version. (e.g. "5.0.11" or "5.1.0" or "5.2-git-96f9771") + + + Returns cat localized for the current language using strings defined under [RadarCategory]. - "Checks whether v1 is equal to v2, without invoking any metamethod." + Checks whether v1 is equal to v2, without invoking any metamethod.
+ rawequal is a core function of Lua's basic library; see the Lua manual for more details. - "Gets the real value of t[index], without invoking any metamethod." + Gets the real value of t[index], without invoking any metamethod.
+ rawget is a core function of Lua's basic library; see the Lua manual for more details. - "Sets the real value of t[index] to value, without invoking any metamethod." - The modified t is then returned. + Sets the real value of t[index] to value, without invoking any metamethod. + The modified t is then returned.
+ rawset is a core function of Lua's basic library; see the Lua manual for more details. [02 ActorDef.lua] Used internally by LoadActor to resolve a path. If optional is true, then a nil path is returned instead of emitting an error if no file is found. @@ -482,18 +559,19 @@ save yourself some time, copy this for undocumented things: [03 UserPreferences2.lua] (internal) Reads the specified user preference from its config file. - Recursively prints all the children of the actor frame to the log file. This can be useful for finding out what actors are on a screen or just seeing what the structure of the actor tree looks like.
+ [02 Utilities.lua] Recursively prints all the children of the actor frame to the log file. This can be useful for finding out what actors are on a screen or just seeing what the structure of the actor tree looks like.
indent is an optional argument that will be prepended to every line. - Recursively prints all values in the table to the log file in the form "(key_type) key: (value_type) value" so that you know the type of the key and the value. Useful if you're not sure exactly what is in a table passed as a parameter.
+ [02 Utilities.lua] Recursively prints all values in the table to the log file in the form "(key_type) key: (value_type) value" so that you know the type of the key and the value. Useful if you're not sure exactly what is in a table passed as a parameter.
indent is an optional argument that will be prepended to every line. Sends the current style to the server. - Loads the specified module. See the Lua manual for more information. + Loads the specified module.
+ require is a core function of Lua's basic library; see the Lua manual for more details. [02 Utilities.lua] Round a number. @@ -508,20 +586,27 @@ save yourself some time, copy this for undocumented things: [02 Colors.lua] Modifies the saturation of the specified color - Saves a screenshot. If pn is nil, saves to the machine's Screenshots dir, otherwise saves to the profile's Screenshots dir. Saves as jpg if compress is true, or png if compress is false. The screenshot is signed if sign is true. prefix and suffix are optional strings to add to the beginning and end of the filename.
+ Saves a screenshot. If pn is nil, saves to the machine's Screenshots dir, otherwise saves to the profile's Screenshots dir. Saves as jpg if compress is true, or png if compress is false. The screenshot is signed if sign is true. prefix and suffix are optional strings to add to the beginning and end of the filename.
Returns success and full path of the resulting screenshot. Scales x, originally within low1 and high1, to fall between low2 and high2. + + [03 Gameplay.lua] Returns the primary ScoreKeeper class to use. + + [02 Colors.lua] + - [00 alias.lua, 02 Other.lua] alias for . + [02 Other.lua] alias for . + + - [00 alias.lua, 02 Other.lua] alias for . + [02 Other.lua] alias for . Returns the current second. @@ -570,15 +655,24 @@ save yourself some time, copy this for undocumented things: [02 ActorDef.lua] Returns true if a decoration should be shown on the current screen or not. + + Returns so localized for the current language using strings defined under [SortOrder]. + [03 CustomSpeedMods.lua] Returns a Lua option row with the custom speed mods defined in SpeedMods.txt. [02 Utilities.lua] Splits a string at every occurence of delimiter, returning a table of the results. + + Returns sa localized for the current language using strings defined under [StageAward]. + [02 Colors.lua] + + Returns i localized for the current language using strings defined under [Stage]. + [02 Colors.lua] @@ -600,58 +694,82 @@ save yourself some time, copy this for undocumented things: [02 Utilities.lua] Look up each value in a table, returning a table with the resulting strings. + + Returns tns localized for the current language using strings defined under [TapNoteScore]. + - [02 TextBanner.lua] This function defines how the TextBanner is laid out. + [02 TextBanner.lua] Defines how the is laid out. + + + [04 Other.lua] [02 Utilities.lua] Converts a string or number to a bool. - Tries to convert e to a number. Returns nil if - it can't convert the input to a number. (base is optional.) + Tries to convert e to a number. Returns nil if it can't convert the input to a number. (base is optional.)
+ tonumber is a core function of Lua's basic library; see the Lua manual for more details. - Converts e to a string. + Converts e to a string.
+ tostring is a core function of Lua's basic library; see the Lua manual for more details. - [02 Enum.lua] Returns a string representing an enum starting from '_'. For example, passing PlayerNumber_P1 to this function will return P1. + [02 Enum.lua] Returns a string representing an enum starting from '_'. For example, passing PlayerNumber_P1 to this function will return "P1". [00 init.lua] Alias for . - Returns the type of the object as a string. See the Lua manual for valid return values. + Returns the type of the object as a string. There are eight basic types in Lua: + nil, boolean, number, string, function, userdata, thread, and table.
+ See the Lua manual for more details. + + + Returns i localized for the current language using strings defined under [UnlockRewardType]. - "Returns the elements from the given table. - This function is equivalent to return list[i], list[i+1], ···, list[j]" - (i and j are optional; "by default, i is 1 and j is the length of the list.") + Returns the elements from table list. This function is equivalent to return list[i], list[i+1], ···, list[j].
+ i and j are optional; by default, i is 1 and j is the length of the list.
+ unpack is a core function of Lua's basic library; see the Lua manual for more details. Returns a string with characters escaped for URLs. (e.g. a space becomes '%20') - This tells Stepmania to update the screen position for any changes to these preferences: CenterImageAddWidth, CenterImageAddHeight, CenterImageTranslateX, CenterImageTranslateY.
+ This tells StepMania to update the screen position for any changes to these preferences: CenterImageAddWidth, CenterImageAddHeight, CenterImageTranslateX, CenterImageTranslateY.
This way, a theme can implement a custom interactive screen for adjusting those preferences. [01 base.lua] Alias for lua.GetThreadVariable. - Returns the current version's build date. + Returns the current version's build date, formatted as YYYYMMDD. - Returns the current version's build time. + Returns the current version's build time, formatted as HH:MM:SS. [00 init.lua] Alias for . + + Returns the current weekday in the range of 0-6, where Sunday is 0. + [04 WidescreenHelpers.lua] Depending on the screen width, scales between ar43 (4:3; 640px) and ar169 (16:9; 854px). [02 Utilities.lua] + + [02 Utilities.lua] + + + [02 Utilities.lua] + + + [02 Utilities.lua] + [02 ActorDef.lua] Wraps the children in an ActorFrame. @@ -667,29 +785,18 @@ save yourself some time, copy this for undocumented things: Returns the current year. - - - [03 ThemePrefs.lua] Returns a Lua option row for toggling AutoSetStyle. - - - [03 ThemePrefs.lua] Returns a Lua option row for displaying the score on ScreenGameplay. - - - [03 ThemePrefs.lua] Returns a Lua option row for displaying the StepsDisplay on ScreenGameplay. - - - [03 ThemePrefs.lua] Returns a Lua option row for determining the fail length. - - - [03 ThemePrefs.lua] Returns a Lua option row for determining the receptor arrow position. - - - [03 ThemePrefs.lua] Returns a Lua option row determining how deep the player options menu should go. - + + The StepMania engine makes some of its namespaces available to Lua. These can be thought of as collections of utility functions.
+ Example using SongUtil to get playable from a song given the current : +

+local song = GAMESTATE:GetCurrentSong()
+local playable_steps = SongUtil.GetPlayableSteps(song)
+
+ Returns the for the file at sPath. @@ -765,20 +872,17 @@ save yourself some time, copy this for undocumented things: Enumerated types are lookup tables associating a string to each numerical value for each Enum. For example, - [1] would be the + PlayerNumber[1] would be the string 'PlayerNumber_P1'.
- The functions defined in the Enum namespace are valid member + The functions in this Enum namespace are valid member functions of every Enum where the first argument is - omitted and the name of the Enum is used in place - of Enum. Instead of - Enum.GetName( - ) or - Enum.Reverse( - ), one can use - :GetName() or - :Reverse(), respectively. + omitted and the name of the Enum is used in place + of Enum.
+ For example:
+ Enum.GetName(PlayerNumber) and + Enum.Reverse(PlayerNumber) can be used like
+ PlayerNumber:GetName() and + PlayerNumber:Reverse(), respectively. Both x and y need to be elements of the enumerated @@ -794,10 +898,12 @@ save yourself some time, copy this for undocumented things: will return the string 'PlayerNumber'. - Returns a reverse lookup table for the enumerated type e. For - example:
local r = - Enum.Reverse( );
- local n = r['PlayerNumber_P2'];
+ Returns a reverse lookup table for the enumerated type e. For + example: +

+local r = PlayerNumber:Reverse()
+local n = r['PlayerNumber_P2']
+
The value of n in this case would be 1 corresponding to the 0-based indexing using in C++ and not 2 as might be expected for the 1-based indexing used in Lua. @@ -874,7 +980,12 @@ save yourself some time, copy this for undocumented things: - + + + Actor is the base class containing common methods that all specialized actor classes inherit. + For example, GetX is a method belonging to Actor, + but s, s, s, and so on can use GetX(). + This adds a wrapper state around the Actor, which is like wrapping the Actor in an ActorFrame, except that you can use it on any actor, and add or remove wrapper states in response to things that happen while the screen is being used. (wrapping an Actor in an ActorFrame normally requires setting it up before the screen starts)
The ActorFrame that is returned is the wrapper state, for convenience.
@@ -935,19 +1046,20 @@ save yourself some time, copy this for undocumented things: Sets Texture Filtering for an Actor to b. - Plays the commands that follow at an accelerated rate (fRate * fRate), where fRate is in seconds. + Plays the commands that follow at an accelerated rate (fRate²), where fRate is in seconds.
+ accelerate is a basic tween command, along with , , , and . Adds a command to the Actor. - Adds rot to the Actor's current x rotation. + Adds rot degrees to the Actor's current X rotation. - Adds rot to the Actor's current y rotation. + Adds rot degrees to the Actor's current Y rotation. - Adds rot to the Actor's current z rotation. + Adds rot degrees to the Actor's current Z rotation. Adds xPos to the Actor's current x position. @@ -974,13 +1086,13 @@ save yourself some time, copy this for undocumented things: Sets the Actor's base alpha to fAlpha, where fAlpha is in the range 0..1. - Sets the Actor's base X rotation to rot. + Sets the Actor's base X rotation to rot degrees. - Sets the Actor's base Y rotation to rot. + Sets the Actor's base Y rotation to rot degrees. - Sets the Actor's base Z rotation to rot. + Sets the Actor's base Z rotation to rot degrees. Sets the Actor's base zoom to zoom. @@ -1010,13 +1122,16 @@ save yourself some time, copy this for undocumented things: [02 Actor.lua] - [02 Actor.lua] Centers an Actor on the screen. (equivalent to x,SCREEN_CENTER_X;y,SCREEN_CENTER_Y) + [02 Actor.lua] Centers an Actor on the screen.
+ self:Center() is equivalent to self:x(SCREEN_CENTER_X):y(SCREEN_CENTER_Y) - [02 Actor.lua] Centers an Actor on the X axis. (equivalent to x,SCREEN_CENTER_X) + [02 Actor.lua] Centers an Actor on the X axis.
+ self:CenterX() is equivalent to self:x(SCREEN_CENTER_X) - [02 Actor.lua] Centers an Actor on the y axis. (equivalent to y,SCREEN_CENTER_Y) + [02 Actor.lua] Centers an Actor on the y axis.
+ self:CenterY() is equivalent to self:y(SCREEN_CENTER_Y) Determines if the z-buffer should be cleared or not. @@ -1039,10 +1154,11 @@ save yourself some time, copy this for undocumented things: Crops percent of the Actor from the top, where percent is in the range 0..1. - Sets the Actor's cull mode to mode. + Sets the Actor's to mode. - Plays the commands that follow at an decelerated rate (1 - (1-fRate) * (1-fRate)), where fRate is in seconds. + Plays the commands that follow at an decelerated rate (1 - (1-fRate) * (1-fRate)), where fRate is in seconds.
+ decelerate is a basic tween command, along with , , , and . Set the Actor's diffuse color to c. @@ -1051,7 +1167,9 @@ save yourself some time, copy this for undocumented things: Sets the Actor's alpha level to fAlpha, where fAlpha is in the range 0..1. - Makes the Actor switch between two colors immediately. See Themerdocs/effect_colors.txt for an example. + Makes the Actor switch between two colors immediately. + See Docs/Themerdocs/effect_colors.txt + for an example. Sets the Actor's bottom edge color to c. @@ -1069,13 +1187,17 @@ save yourself some time, copy this for undocumented things: Sets the Actor's lower right corner color to c. - Makes the Actor switch between two colors, jumping back to the first after reaching the second. See Themerdocs/effect_colors.txt for an example. + Makes the Actor switch between two colors, jumping back to the first after reaching the second. + See Docs/Themerdocs/effect_colors.txt + for an example. Sets the Actor's right edge color to c. - Makes the Actor shift between two colors smoothly. See Themerdocs/effect_colors.txt for an example. + Makes the Actor shift between two colors smoothly. + See Docs/Themerdocs/effect_colors.txt + for an example. Sets the Actor's top edge color to c. @@ -1178,8 +1300,8 @@ save yourself some time, copy this for undocumented things: Returns the Actor's current effect delta. - - Returns the Actor's current effect magnitude as three floats (not one; I hate Lua.xsd). + + Returns the Actor's current effect magnitude as three floats. Returns the Actor's current glow color. @@ -1196,15 +1318,17 @@ save yourself some time, copy this for undocumented things: Returns the Actor's current height. - + + Returns the Actor's current X, Y, and Z rotation in degrees as three separate floats. + - Returns the Actor's current X rotation. + Returns the Actor's current X rotation in degrees. - Returns the Actor's current Y rotation. + Returns the Actor's current Y rotation in degrees. - Returns the Actor's current Z rotation. + Returns the Actor's current Z rotation in degrees. Returns the number of seconds into the currently running effect (e.g. diffuseshift, bob). @@ -1231,13 +1355,19 @@ save yourself some time, copy this for undocumented things: Sets the Actor's glow color. - Makes the Actor glow between two colors immediately. See Themerdocs/effect_colors.txt for an example. + Makes the Actor glow between two colors immediately. + See Docs/Themerdocs/effect_colors.txt + for an example. - Makes the Actor glow between two colors smoothly, jumping back to the first at the end. See Themerdocs/effect_colors.txt for an example. + Makes the Actor glow between two colors smoothly, jumping back to the first at the end. + See Docs/Themerdocs/effect_colors.txt + for an example. - Makes the Actor glow between two colors smoothly. See Themerdocs/effect_colors.txt for an example. + Makes the Actor glow between two colors smoothly. + See Docs/Themerdocs/effect_colors.txt + for an example. Set the fractional horizontal alignment of the Actor according to fAlign which should be a float in the range 0..1. An alignment of 0 is left aligned while an alignment of 1 is right aligned. See for the common case. @@ -1261,7 +1391,8 @@ save yourself some time, copy this for undocumented things: Hurries up an Actor's tweening by factor. - Plays the commands that follow at a normal rate, where fRate is in seconds. + Plays the commands that follow at a normal (linear) rate, where fRate is in seconds.
+ linear is a basic tween command, along with , , , and . [02 Lyrics.lua] Plays the lyric command for the specified side ("Back" or "Front"). @@ -1300,13 +1431,13 @@ save yourself some time, copy this for undocumented things: Sets the roll of this Actor to fRoll. - Set the Actor's rotation on the X axis to fAlign. + Set the Actor's rotation on the X axis to fRotation degrees. - Set the Actor's rotation on the Y axis to fAlign. + Set the Actor's rotation on the Y axis to fRotation degrees. - Set the Actor's rotation on the Z axis to fAlign. + Set the Actor's rotation on the Z axis to fRotation degrees. @@ -1366,7 +1497,9 @@ save yourself some time, copy this for undocumented things: Tells the Actor to spin. Can use to define different spinning behavior. - + + spring is a basic tween command, along with , , , and . + Stops any effect the Actor has. @@ -1383,8 +1516,11 @@ save yourself some time, copy this for undocumented things: Determines if the Actor should use texture wrapping or not. - Uses type to determine the tween to use. The type must be one of the TweenType enum values. If the type is note TweenType_Bezier, the params table is ignored. If the type is TweenType_Bezier, then the params table must have 4 or 8 numbers. 4 numbers in the params creates a 1 dimensional bezier curve, 8 numbers creates a 2 dimensional bezier curve.
- It's usually more convenient to use Actor:linear, Actor:accelerate, and so on, rather than using Actor:tween directly. + Generic method for tweening an actor.
+ time is in seconds. type is a
+ If the type is TweenType_Bezier, then the params table must have 4 or 8 numbers. 4 numbers creates a 1 dimensional bezier curve, 8 numbers creates a 2 dimensional bezier curve.
+ If the type is not TweenType_Bezier, the params table is ignored.
+ It's usually more convenient to use , , , or rather than using Actor:tween() directly. Set the fractional vertical alignment of the Actor according to fAlign which should be a float in the range 0..1. An alignment of 0 is top aligned while an alignment of 1 is bottom aligned. See for the common case. @@ -1475,7 +1611,67 @@ save yourself some time, copy this for undocumented things: Sets the x and y location of the Actor in one command. - + + + ActorFrames are containers that allow multiple children actors to be grouped and scripted together.
+ In theming, the StepMania engine expects a screen layer (underlay, overlay, decorations, in, out, cancel) + file to return one actor, and it is common to return one ActorFrame that contains many actors of various + specialization.
+ A common convention is to add children at the next index (current size of the table plus 1).
+ Basic example: +

+-- in the context of a lua file as a screen layer
+-- this ActorFrame is a table
+local af = Def.ActorFrame{}
+
+-- add a Sprite at the next index
+af[#af+1] = Def.Sprite{
+	Texture="smilingsun.png"
+}
+
+-- add a BitmapText at the next index
+af[#af+1] = Def.BitmapText{
+	Font="Common normal",
+	Text="Yo!"
+}
+
+-- have the file return the ActorFrame
+-- for the StepMania engine to interpret
+return af
+
+ When actor commands like and + are used position and scale an ActorFrame, its children will position relative to the parent ActorFrame + and scale proportionally.
+ For example, if you want to animate 50 actors moving 100px to the right in unison, it is easier to move the + parent ActorFrame than each actor individually.
+ Basic example: +

+local af = Def.ActorFrame{}
+
+-- move the ActorFrame +100px
+-- over a 2 second duration
+-- its children will move with it
+af.OnCommand=function(self)
+	self:linear(2):addx(100)
+end
+
+-- add various children actors
+-- to the parent ActorFrame
+af[#af+1] = Def.Sprite{
+	Texture="taro.png"
+}
+
+af[#af+1] = Def.Sprite{
+	Texture="laer.png"
+}
+
+-- etc.
+
+return af
+
+ ActorFrames can contain ActorFrames, and doing so is good design for sufficiently complex screens. + + Adds a child to the ActorFrame from the specified path. @@ -1483,14 +1679,14 @@ save yourself some time, copy this for undocumented things: Sets the field of view for the ActorFrame. - Returns the child with a name of sName.
- If there are multiple children with that name, returns an array of those children.
+ Returns the child with a name of sName.
+ If there are multiple children with that name, returns an array of those children.
The table also acts as a pass through layer, function calls pass through to the last child of that name. - Returns a table of all the children in the ActorFrame.
- The table is indexed by the names of the children.
- If there are multiple children with the same name, the entry for that name is an array of those children.
+ Returns a table of all the children in the ActorFrame.
+ The table is indexed by the names of the children.
+ If there are multiple children with the same name, the entry for that name is an array of those children.
The table also acts as a pass through layer, function calls pass through to the last child of that name. @@ -1560,7 +1756,7 @@ save yourself some time, copy this for undocumented things: Sets the vanishing point for the ActorFrame. - + Creates the ActorFrameTexture. @@ -1583,7 +1779,7 @@ save yourself some time, copy this for undocumented things: Sets the Texture's name to sName. - + Adds a texture to the ActorMultiTexture. Returns the number of texture units. @@ -1603,7 +1799,7 @@ save yourself some time, copy this for undocumented things: Sets a TextureMode on the specified index. - + The list of quad states is used to determine which animation state is used for each quad. The offset is added to the AMV's current state, and the resulting state is used. @@ -1701,17 +1897,19 @@ save yourself some time, copy this for undocumented things: Sets the draw state variables to the values in the table.
- Mode must be a DrawMode.
- First is the index of the first vertex to draw.
- Num is the number of vertices to draw. -1 for Num means draw all verts after First.
+ Mode must be a .
+ First is the index of the first vertex to draw.
+ Num is the number of vertices to draw. -1 for Num means draw all verts after First.
Any value not in the table defaults to the already set value.
- Examples:
- -- Sets all three parts of the draw state.
- self:SetDrawState{Mode="DrawMode_Quads", First= 1, Num= -1}
- -- Set only the draw mode. First and Num remain unchanged from previous.
- self:SetDrawState{Mode="DrawMode_Quads"}
- -- Set the first and number to draw. Draw mode remains unchanged.
- self:SetDrawState{First= 3, Num= 4}
+ Examples: +

+-- Sets all three parts of the draw state.
+self:SetDrawState{Mode="DrawMode_Quads", First= 1, Num= -1}
+-- Set only the draw mode.  First and Num remain unchanged from previous.
+self:SetDrawState{Mode="DrawMode_Quads"}
+-- Set the first and number to draw.  Draw mode remains unchanged.
+self:SetDrawState{First= 3, Num= 4}
+
 Get the DrawMode of the destination tween state. @@ -1750,7 +1948,7 @@ save yourself some time, copy this for undocumented things: Sets the texture at from the file path path. - + Returns the target of the ActorProxy. @@ -1758,7 +1956,7 @@ save yourself some time, copy this for undocumented things: Sets the ActorProxy target to a. - + Returns the scroller's current item. @@ -1845,13 +2043,32 @@ save yourself some time, copy this for undocumented things: Sets the scroller's transform function from fItemWidth. - + - This Actor represents a playable sound. Though the C++ class is ActorSound, it is accessible to Lua via Def.Sound.
- There are three attributes that can be set as booleans on load:
+ This actor represents a playable sound. Though the C++ class is ActorSound, it is accessible to Lua via Def.Sound.
+ You must provide ActorSounds with a filepath to the asset using their File attribute. +

+Def.Sound{
+	File="./path/to/soundeffect.ogg",
+	OnCommand=function(self)
+		-- play this sound effect at the parent screen's OnCommand
+		self:play()
+	end
+}
+
+ ActorSounds have three additional boolean attributes:
• SupportPan - Let the sound pan from side to side.
• SupportRateChanging - Let the sound change rate and pitch.
- • IsAction - If true, the sound is an action sound, and will be muted if the MuteActions preference is turned on. + • IsAction - If true, the sound is an action sound, and will be muted if the MuteActions preference is turned on.
+ Basic example: +

+Def.Sound{
+	File="./path/to/soundeffect.ogg",
+	SupportPan=true,
+	SupportRateChanging=true,
+	IsAction=false,
+}
+
 Returns the that can be played by this Actor. @@ -1879,6 +2096,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via ANNOUNCER. + Returns true if Announcer sAnnouncer exists. @@ -1893,6 +2113,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via HOOKS. + Returns true if the application presently has focus. @@ -1900,17 +2123,17 @@ save yourself some time, copy this for undocumented things: Returns the name of the architecture in use. - + Returns true if the Banner is currently scrolling. - + Loads the background from an UnlockEntry. - + Loads the banner from an UnlockEntry. @@ -1944,7 +2167,41 @@ save yourself some time, copy this for undocumented things: - + + + BitmapText actors are used to display text on-screen.
+ The font can be specified using the Font attribute. It takes a font name a string, + pathed relative to the current theme's ./Fonts/ directory.
+ StepMania expects fonts to be formatted as spritesheets with accompanying ini files. + These can be generated from ttf files using Texture Font Generator.exe in the + ./Program/ directory of packaged StepMania releases.
+ The text displayed can be initially set using the Text attribute, and changed + later using settext().
+ Basic usage example: +

+Def.BitmapText{
+	Font="Common normal",
+	Text="Hello!",
+	OnCommand=function(self)
+		self:sleep(2):settext("Hey!")
+	end
+}
+
+
+ The font can alternatively be specified with the File attribute, + which takes the path to the ini file as a string, relative to the root of StepMania.
+ Basic example: +

+-- use a custom font from a simfile
+local song_dir = GAMESTATE:GetCurrentSong():GetSongDir()
+local ini_path = "Fonts/courier/_courier 20px.ini"
+
+Def.BitmapText{
+	File=song_dir .. ini_path,
+	Text="Hello, World!"
+}
+
+ Add the attribute attr to the string at position iPos.
@@ -2031,7 +2288,7 @@ save yourself some time, copy this for undocumented things: Wrap the unzoomed text at iWidth pixels. If you or by x and you want the text wrapped at width, then you should use wrapwidthpixels(width/x). - + Returns the text that is currently set at the exact moment you call it. This is likely only going to be useful in an Update command. @@ -2084,6 +2341,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via CHARMAN. + Returns a table of all characters installed. @@ -2097,7 +2357,7 @@ save yourself some time, copy this for undocumented things: Returns the number of characters available. - + Loads the ComboGraph commands from the Metrics in group sMetricsGroup. @@ -2105,7 +2365,7 @@ save yourself some time, copy this for undocumented things: Sets the values of the ComboGraph using the specified StageStats and PlayerStageStats. - + Loads the ControllerStateDisplay from the specified GameController. @@ -2199,7 +2459,7 @@ save yourself some time, copy this for undocumented things: Returns true if the Course is a ranking course. - + Sets the CourseContentsList from the GameState. @@ -2232,6 +2492,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via CRYPTMAN. + Generates a random UUID (version 4). @@ -2334,7 +2597,13 @@ save yourself some time, copy this for undocumented things: Destroys the spline, freeing the memory allocated for it. This can only be called on splines created with create_spline(). - + + + A newline-delimited list of available input devices.
+ The list shown will the same as that returned by INPUTMAN:GetDescriptions(), but with "MonkeyKeyboard" removed. + + + Sets the DifficultyIcon's state from the difficulty passed in. @@ -2408,7 +2677,7 @@ save yourself some time, copy this for undocumented things: - + Returns the index of the last banner loaded. @@ -2449,7 +2718,7 @@ save yourself some time, copy this for undocumented things: See . - + Sets the StepsDisplayList from the GameState. @@ -2534,6 +2803,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via GAMEMAN. + Return the first for the specified game. @@ -2543,7 +2815,7 @@ save yourself some time, copy this for undocumented things: Return the localized string representation of st. - + Returns a table of all selectable games. @@ -2557,6 +2829,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via SOUND. + Set the music volume to fVolume for fDuration seconds. @@ -2587,6 +2862,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via GAMESTATE. + Adds another stage to the specifed player. @@ -2606,15 +2884,17 @@ save yourself some time, copy this for undocumented things: The second argument is optional. Apply the GameCommand represented by sCommand for pn, if given. See . - - Checks various things to determine whether the game will crash when gameplay starts. Returns false and a string if gameplay cannot be entered safely.
+ + Checks various things to determine whether the game will crash when gameplay starts. Returns false and an error string if gameplay cannot be entered safely.
Might not work in all cases, but will catch things like a player not having steps set or no current song or style. Mainly exists for people with a custom ScreenSelectMusic replacement.
- Example:
- local can, reason= GAMESTATE:CanSafelyEnterGameplay()
- if not can then
- lua.ReportScriptError("Cannot safely enter gameplay: " .. tostring(reason))
- end
+ Example: +

+local can, reason = GAMESTATE:CanSafelyEnterGameplay()
+if not can then
+	lua.ReportScriptError("Cannot safely enter gameplay: " .. tostring(reason))
+end
+
 Removes any stage modifiers that are illegal for course play. @@ -2634,7 +2914,7 @@ save yourself some time, copy this for undocumented things: Returns the current for the specified . - + Returns the current . @@ -2988,7 +3268,7 @@ save yourself some time, copy this for undocumented things: Unjoins player pn. - + Loads the GradeDisplay commands from the Metrics in group sMetricsGroup. @@ -2996,7 +3276,7 @@ save yourself some time, copy this for undocumented things: Sets the GradeDisplay to show Grade g. - + Loads the GraphDisplay commands from the Metrics in group sMetricsGroup. @@ -3004,7 +3284,7 @@ save yourself some time, copy this for undocumented things: Sets the values of the GraphDisplay using the specified StageStats and PlayerStageStats. - + Sets the GrooveRadar values for Player pn to empty. @@ -3015,7 +3295,7 @@ save yourself some time, copy this for undocumented things: Sets the GrooveRadar values for Player pn to the specified (floating point) values in the table. - + Returns two tables representing the tips and alternate tips in the HelpDisplay. @@ -3090,12 +3370,15 @@ save yourself some time, copy this for undocumented things: Returns the rank of the highest score for name in the list. Returns 0 if there is no score for name in the list. (returns 1 if name has the top score, 2 if name has the second place score, and so on) - + Loads the HoldJudgment for the specified MultiPlayer. + + This singleton is accessible to Lua via INPUTFILTER. + Returns the mouse wheel value. @@ -3106,6 +3389,11 @@ save yourself some time, copy this for undocumented things: Returns the Y position of the mouse. + + + A newline-delimited list of inputs that are currently being pressed. It will update as inputs are held and released. Handy for custom TestInput screens. + + Returns the amount of life left in the LifeMeter as a float in the range 0..1. @@ -3132,6 +3420,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via MEMCARDMAN. + Returns true if player pn's card is locked. @@ -3171,11 +3462,14 @@ save yourself some time, copy this for undocumented things: Sets the MenuTimer's stealth setting to bStealth. If true, the timer will be invisible and silent. - + Stops the MenuTimer by setting it to 0 and pausing. + + This singleton is accessible to Lua via MESSAGEMAN. + Broadcast the message to all listeners subscribed to sMessage. The second argument is an optional table of parameters. It may be omitted or explicitly @@ -3185,12 +3479,12 @@ save yourself some time, copy this for undocumented things: Sets whether logging of messages is enabled. If log is true, all messages that pass through Broadcast (from the engine for from the theme or from anywhere else), will be logged with Trace. - + Sets the width of the MeterDisplay to fWidth. - + Returns the model's default animation. @@ -3214,7 +3508,7 @@ save yourself some time, copy this for undocumented things: Returns the number of states the Model has. - + Loads the ModIconRow of Player pn from the Metrics in group sMetricsGroup. @@ -3240,6 +3534,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via NOTESKIN. + Returns a string from the specified element and value. @@ -3419,12 +3716,12 @@ save yourself some time, copy this for undocumented things: Returns true if this row forces one choice on all players. - + Sets the PaneDisplay from the GameState. - + Sets the PercentageDisplay from the specified PlayerState and PlayerStageStats. @@ -3457,12 +3754,12 @@ save yourself some time, copy this for undocumented things: - All these functions have an optional last argument: If the last argument is the boolean value true, then instead of returning the previous settings as normal, they will instead return the PlayerOptions object.
+ All these functions have an optional last argument: If the last argument is the boolean value true, then instead of returning the previous settings as normal, they will instead return the PlayerOptions object.
This allows you to chain them like this:
- player_options:Twirl(5, 1, true):Roll(5, true):Dizzy(true):Twirl()
+ player_options:Twirl(5, 1, true):Roll(5, true):Dizzy(true):Twirl()

- Special note: Functions that take a bool as their arg must have true as the second arg to be used with chaining.
- "player_options:Backwards(true, true):Beat(5)" will chain, "player_options:Backwards(true):Beat(5)" will not chain.
+ Functions that take a bool as their arg must have true as the second arg to be used with chaining.
+ player_options:Backwards(true, true):Beat(5) will chain. player_options:Backwards(true):Beat(5) will not chain.

Most options fall into one of four types: float, int, bool, or enum.
Float type options have this interface:
@@ -3471,15 +3768,25 @@ save yourself some time, copy this for undocumented things: If approach_speed is a float, sets the speed of the transition to approach_speed. Returns the previous values of both.
approach_speed is in units of n per second. value will be approached at the rate of approach_speed per second.
Note that the value and the approach speed arguments are both independently optional.
- Example:
- a,b= options:Boost() -- Sets a to the current value and b to the current approach_speed.
- a,b= options:Boost(5, .5) -- Stores the previous values in a and b, NOT to 5 and .5. Sets the value to 5 and the approach speed to .5.
- a,b= options:Boost(5) -- Sets a and b to the previous values, NOT to 5 and .5. Sets the value to 5 and leaves the approach speed at whatever it was.
+ Example: +

+-- Sets a to the current value and b to the current approach_speed
+a,b = options:Boost()
+
+-- Stores the previous values in a and b, NOT to 5 and .5
+-- Sets the value to 5 and the approach speed to .5
+a,b = options:Boost(5, .5)
+
+-- Sets a and b to the previous values, NOT to 5 and .5
+-- Sets the value to 5 and leaves the approach speed at whatever it was
+a,b = options:Boost(5)
+

Setting the approach speed only matters when modifying the PlayerOptions from ModsLevel_Song.
Int type options are similar to float in that they return and take a number, but they do not have an approach speed.
Bool type options have an almost identical interface, the difference is that they can not have an approach speed.
Enum type options are almost identical to bool type. They take and return an enum value.
+ For brevity, the functions are only given a description if the option requires careful handling or does not follow the float or bool interfaces.
 @@ -3634,7 +3941,7 @@ save yourself some time, copy this for undocumented things: - + Returns true if step attacks or random attacks are enabled. @@ -3708,11 +4015,18 @@ save yourself some time, copy this for undocumented things: - Sets the NoteSkin to the named noteskin, unless name is nil or the noteskin does not exist. Returns the name of the previous noteskin and whether the set attempt succeeded.
- Changing the noteskin during a song is not supported.
- Example:
- note_name= options:NoteSkin() -- Sets note_name to the player's current noteskin.
- prev_note_name, succeeded= options:NoteSkin("cel") -- Sets prev_note_name to the noteskin the player had set, changes the current noteskin to "cel", sets succeeded to true if the "cel" noteskin exists.
+ Sets the NoteSkin to the named noteskin, unless name is nil or the NoteSkin does not exist. Returns the name of the previous NoteSkin and whether the set attempt succeeded.
+ Changing the NoteSkin during gameplay is not supported.
+ Example: +

+-- Sets note_name to the player's current noteskin
+note_name = options:NoteSkin()
+
+-- Sets prev_note_name to the noteskin the player had set
+-- changes the current noteskin to "cel"
+-- sets succeeded to true if the "cel" noteskin exists.
+prev_note_name, succeeded = options:NoteSkin("cel")
+
 If the player is using Overhead (0 tilt, 0 skew), returns true.
@@ -3975,9 +4289,13 @@ save yourself some time, copy this for undocumented things: Returns true if the player was disqualified from ranking. + + Sets the Dance Point limits of the stage. + + @@ -4018,6 +4336,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via PREFSMAN. + Return the value of the preference sPreference. @@ -4240,6 +4561,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via PROFILEMAN. + Returns the Profile for the specified profile ID. @@ -4307,6 +4631,11 @@ save yourself some time, copy this for undocumented things: Sets the current stats prefix. The stats prefix is prepended to the Stats.xml file when loading or saving a profile. SetStatsPrefix will reload all profiles from the Stats.xml that has the given prefix. In general, score entries are the only thing not preserved when changing the stats prefix. Profile::HandleStatsPrefixChange in Profile.cpp lists the fields that are preserved. + + + Quads are rectangular actors that players can see. A Quad can have color, size, position, etc. + + Returns the value of rc from . @@ -4339,6 +4668,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via DISPLAY. + Return the height of the display. @@ -4418,6 +4750,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via FILEMAN. + Returns true if a file exists at sPath. @@ -4432,8 +4767,11 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via INPUTMAN. + - Return an array of connected input device descriptions. + Returns an array of connected input device descriptions. @@ -4527,7 +4865,7 @@ save yourself some time, copy this for undocumented things: Reloads the texture. - + Loads the metrics for this RollingNumbers from sGroupName. @@ -4535,30 +4873,102 @@ save yourself some time, copy this for undocumented things: Sets the target number to f. - + + + Screen is the base screen class containing common methods that all specialized screens inherit.
+ By itself, Screen does not have the layers (underlay, overlay, decorations, in, out, cancel) commonly + used in theming, so themers designing custom screens typically use as + the screen class for such endeavors. + - This adds the lua function "callback" to the list of functions the screen will pass input to. Whenever an input event occurs, callback will be passed a table with the details of the event. callback must return a bool to indicate whether the event was handled. If callback returns true, the event will not be passed any further.
- This should not be used to provide text input because that would not handle localization or different keyboard layouts.
- The screen and the callbacks will both be passed input events, so be aware of what input the current screen responds to and consider the effects.
- Details of the table containing the event data:
- {
- DeviceInput= { -- The raw details of the event.
- device= string, -- The type of device. The first half of the string will be "Device_", the second half will be from InputDeviceNames in RageInputDevice.cpp.
- button= string, -- The button that was pressed. the first half of the string will be "DeviceButton_", the second half will be from InitNames in RageInputDevice.cpp.
- level= float, -- A floating point value for analog input.
- z= float, -- Mousewheel input.
- down= bool, -- Whether the button is down. This is level with a threshold and debouncing applied.
- ago= float, -- How long ago this input occurred, in seconds.
- is_joystick= bool, -- True if the device is a joystick.
- is_mouse= bool -- True if the device is a mouse.
- }, -- This ends the list of things inside the DeviceInput part of the table.
- controller= string, -- The game controller this event was mapped to. "GameController_1" or "GameController_2", or nil if the event wasn't mapped to either controller.
- button= string, -- The semi-raw button that was pressed. This is what the button was mapped to by the keymap settings, but without the conversions that occur when OnlyDedicatedMenuButtons is true. Will be empty if the button was not mapped.
- type= string, -- The type of event. "InputEventType_FirstPress", "InputEventType_Repeat", or "InputEventType_Release".
- GameButton= string, -- The cooked button that was pressed. This is button with mapping that occurs when OnlyDedicatedMenuButtons is true applied. This is nil for unmapped buttons.
- PlayerNumber= PlayerNumber, -- The player that the controller is mapped to, or nil.
- MultiPlayer= string, -- Unknown purpose.
- } + This adds the Lua function callback to the list of functions the screen will pass input to, giving Lua access to player input as it occurs.
+ When an input event occurs, callback will be passed a table with the details of the event. callback must return a bool to indicate whether the event was handled. If callback returns true, the event will not be passed any further.
+ This method does not handle localization or different keyboard layouts, so is better suited to getting text input from players.
+ Be aware that both the screen (as handled by the StepMania engine) and your Lua callbacks will be passed input events, and this can result in undesirable side effects.
+ Basic usage example: +

+local InputHandler = function( event )
+	-- do something cool with the event table in here :)
+	-- the details of the event table are documented below
+
+	-- example:
+	-- show the GameButton that was most recently pressed/held
+	if event.type ~= "InputEventType_Release" then
+		SCREENMAN:SystemMessage( event.GameButton )
+	end
+
+	return false
+end
+
+Def.ActorFrame{
+	OnCommand=function(self)
+		SCREENMAN:GetTopScreen():AddInputCallback( InputHandler )
+	end
+}
+
+ +Details of the event table: +

+{
+	-- The "semi-raw" button that was pressed. This is what
+	-- the button was mapped to by the keymap settings, without
+	-- the conversions that occur when OnlyDedicatedMenuButtons
+	--  is true. Will be empty if the button was not mapped.
+	button = string,
+
+	-- "InputEventType_FirstPress", "InputEventType_Repeat",
+	-- or "InputEventType_Release".
+	type = string,
+
+	-- The "cooked" button that was pressed.  This is button with
+	-- mapping that occurs when OnlyDedicatedMenuButtons is true
+	-- applied.  This is nil for unmapped buttons.
+	GameButton = string,
+
+	-- The player that the controller is mapped to, or nil.
+	PlayerNumber = PlayerNumber,
+
+	-- The game controller this event was mapped to.
+	-- "GameController_1" or "GameController_2", or nil if the event
+	-- wasn't mapped to either controller.
+	controller = string,
+
+	-- The details of the event.
+	DeviceInput = {
+		-- The type of device.  The first half of the string will
+		-- be "Device_", the second half will be from InputDeviceNames
+		-- in RageInputDevice.cpp.
+		device = string,
+
+		-- The button that was pressed. The first half of the string
+		-- will be "DeviceButton_", the second half will be from InitNames
+		-- in RageInputDevice.cpp.
+		button = string,
+
+		-- A floating point value for analog input.
+		level = float,
+
+		-- Mousewheel input.
+		z = float,
+
+		-- Whether the button is down.  This is level with a threshold
+		-- and debouncing applied.
+		down = bool,
+
+		-- How long ago this input occurred, in seconds.
+		ago = float,
+
+		-- True if the device is a joystick.
+		is_joystick = bool,
+
+		-- True if the device is a mouse.
+		is_mouse = bool
+	},
+
+	-- Unknown purpose. SMOnline?
+	MultiPlayer = string
+}
+
 Returns the name of the next Screen. @@ -4591,17 +5001,19 @@ save yourself some time, copy this for undocumented things: [02 Other.lua] Gets a string from the current Screen in the current language. - + + + Returns the current . - + Returns the current StageStats. - + This should behave identically to the normal back button behavior. This function is for the pause menu to use when the player forfeits or restarts, so that a score isn't saved. @@ -4630,19 +5042,19 @@ save yourself some time, copy this for undocumented things: This is part of the system for controlling how haste behaves.
- Read Docs/Themerdocs/haste.txt. + See Docs/Themerdocs/haste.txt. This is part of the system for controlling how haste behaves.
- Read Docs/Themerdocs/haste.txt. + See Docs/Themerdocs/haste.txt. This is part of the system for controlling how haste behaves.
- Read Docs/Themerdocs/haste.txt. + See Docs/Themerdocs/haste.txt. This is part of the system for controlling how haste behaves.
- Read Docs/Themerdocs/haste.txt. + See Docs/Themerdocs/haste.txt. Sets the next Screen to be loaded. @@ -4654,12 +5066,15 @@ save yourself some time, copy this for undocumented things: Pauses or unpauses the game, depending on the value of bPause. - + Returns the LifeMeter. + + This singleton is accessible to Lua via SCREENMAN. + Adds a screen at the top of the screen stack. (sMessage is an optional ScreenMessage posted once the new screen is finished.) @@ -4667,7 +5082,7 @@ save yourself some time, copy this for undocumented things: Gets the screen at the top of the screen stack. - Returns whether the input for the player has been redirected away from the normal screen input function. Input that has been redirected is only sent to lua input callbacks. + Returns whether the input for the player has been redirected away from the normal screen input function. Input that has been redirected is only sent to Lua input callbacks. Plays the invalid sound. @@ -4697,14 +5112,14 @@ save yourself some time, copy this for undocumented things: Sets the next screen to s. - Sets whether the input for the player has been redirected away from the normal screen input function. Input that has been redirected is only sent to lua input callbacks.
- This can be useful when putting a custom menu on a screen, and you want to disable the built in actors while the menu is open. Then you handle input through an input callback until the player closes the menu. + Sets whether the input for the player has been redirected away from the normal screen input function. Input that has been redirected is only sent to Lua input callbacks.
+ This can be useful when putting a custom menu on a screen, and you want to disable the built in actors while the menu is open. You can handle input through an input callback until the player closes the menu. Broadcasts a system message. - + Returns true if Player pn backspaced successfully. @@ -4732,12 +5147,18 @@ save yourself some time, copy this for undocumented things: Gets the currently selected letter of Player pn. - + Returns the number of active players. - + + + + + + + Returns true if all active players are on the last options row. @@ -4754,12 +5175,12 @@ save yourself some time, copy this for undocumented things: Returns the specified OptionRow. - + Returns true if we are going to PlayerOptions. - + Continues to the next screen. @@ -4767,7 +5188,7 @@ save yourself some time, copy this for undocumented things: Returns true if there is a profile that can be loaded. - + Continues to the next screen. @@ -4775,12 +5196,12 @@ save yourself some time, copy this for undocumented things: Returns true if there is a profile that can be saved. - + Returns player pn's current selected item as an integer. - + Returns false if the options list is already open or the UseOptionsList metric is false. @@ -4800,7 +5221,7 @@ save yourself some time, copy this for undocumented things: [02 StageMods.lua] Sets up modifiers for non-course modes. - + Tells the screen to go to the previous screen. @@ -4812,21 +5233,79 @@ save yourself some time, copy this for undocumented things: Returns the profile index of the specified Player. - Sets the profile index of Player pn to iProfileIndex.
- The following values of iProfileIndex have special, hardcoded behavior:
- • -1: join the player and play the theme's start sound effect
+ Sets the profile index of Player pn to iProfileIndex.
+ The following values of iProfileIndex have special, hardcoded behavior:
+ • -1: join the player and play the theme's start sound effect
• -2: unjoin the player, unlock their MemoryCard, and unmount their MemoryCard - + - TextEntrySettings is implemented similar to the Attributes in BitmapText. Formatting issues prevent the sample from being properly shown here.
Please see docs/Themerdocs/ScreenTextEntry.txt for the TextEntrySettings format. + Using ScreenTextEntry is the preferred way to get text input from players.
+ For theming, ScreenTextEntry is unique because it is typically added temporarily to the engine's + screen stack to be popped off the stack when the player is done entering text.
+ As such, it is commonly styled to appear to players as an overlay or modal.
+ Basic usage example: +

+local args = {
+	Question="Do you like Waffles?",
+	InitialAnswer="Yeah, we like waffles!",
+	MaxInputLength=300,
+	OnOK=function(answer)
+		-- answer is what the player typed
+		local msg = "Your response was: " .. answer
+		SCREENMAN:SystemMessage(msg)
+	end
+}
+
+SCREENMAN:AddNewScreenToTop("ScreenTextEntry")
+SCREENMAN:GetTopScreen():Load( args )
+
 - Sets up a ScreenTextEntry's values. + Sets up a ScreenTextEntry's values using args.
+ TextEntrySettings is special struct for ScreenTextEntry, and + as a Lua table, it should contain specific attributes: +

+local args = {
+	-- ScreenMessage to send on pop
+	-- optional, "SM_None" if omitted
+	SendOnPop = "",
+
+	-- the question text to display
+	Question = "",
+
+	-- initial answer text
+	InitialAnswer = "",
+
+	-- Maximum amount of characters
+	MaxInputLength = 0,
+
+	-- mask character input (optional)
+	Password = false,
+
+	-- validation function
+	-- must return boolean and string
+	Validate = function(answer, errorStr) end,
+
+	-- function called on ok
+	OnOK = function(answer) end,
+
+	-- function called on cancel
+	OnCancel = function() end,
+
+	-- Validate appending a character 
+	-- must return boolean
+	ValidateAppend = function(answer, append) end,
+
+	-- Format answer for display
+	-- must return string
+	FormatAnswerForDisplay = function(answer) end
+}
+
 - + Tells the screen to go to the previous screen. @@ -4840,26 +5319,32 @@ save yourself some time, copy this for undocumented things: Sets whether the screen allows late joining. This only works for screens that are just ScreenWithMenuElements, as most derived screens have their own hard coded function for whether late joining is allowed. + + Returns an array of all the available objects for a . - Returns the path to the song's background image. + Returns the path to the song's background image.
+ If the stepartist did not provide a path for a background, this returns nil. - Returns the path to the song's banner. + Returns the path to the song's banner.
+ If the stepartist did not provide a path for a banner, this returns nil. Returns a table with all the data for the song's BGCHANGES line.
Each element of the table is one change like this:
- {start_beat= 1.0, rate= 1.0, transition= "example", effect= "example", file1= "example", file2= "example", color1= "#FFFFFFFF", color2= "#FFFFFFFF"} + {start_beat=1.0, rate=1.0, transition="example", effect="example", file1="example", file2="example", color1="#FFFFFFFF", color2="#FFFFFFFF"} - Returns the path to the song's CD image. + Returns the path to the song's CD image.
+ If the stepartist did not provide a path for a CDImage, this returns nil. - Gets the path to the CDTitle. + Gets the path to the CDTitle.
+ If the stepartist did not provide a path for a CDTitle, this returns nil. Returns the path to the song's disc image (different from CD, think Pump). @@ -4871,13 +5356,17 @@ save yourself some time, copy this for undocumented things: Returns a table of 2 floats containing the display BPMs. - Returns the displayed full title of the song, including subtitle. + Returns the displayed full title of the song.
+ The full title is, at minimum, the main title. + If the subtitle is not an empty string, + the full title is main title + " " + subtitle. Returns the displayed main title of the song. - Returns the displayed subtitle of the song. + Returns the displayed subtitle of the song.
+ If the stepartist did not provide a subtitle, this returns an empty string. Returns the first beat of the song. @@ -5041,6 +5530,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via SONGMAN. + Returns true if the specified course group exists. @@ -5071,8 +5563,8 @@ save yourself some time, copy this for undocumented things: Returns a table with all of the courses in the specified group. - - Returns the extra stage info (Song, Steps) for the specified Style s. (If bExtra2 is true, it will use the second Extra Stage data instead of the first. Again, Lua.xsd sucks) + + Returns the extra stage info (Song, Steps) for the specified Style s. If b2ndExtra is true, it will use the second Extra Stage data instead of the first. Returns the number of courses loaded via Additional folders. @@ -5216,7 +5708,26 @@ save yourself some time, copy this for undocumented things: Returns the warp destination length. - + + + Sprite actors can be used to display images and video. If you want to load a png as part of your UI, + or animate a visual effect from a sprite sheet, or play a video file, Sprite is what you're looking for.
+
+ You can initialize Sprites with a filepath to the graphic asset using their Texture attribute. +

+local spr = Def.Sprite{
+	Texture="path/to/mycoolimage.png"
+}
+
+ Frame-based animated sprites can be initialized with the Frames attribute. +

+local spr = Def.Sprite{
+	Texture="path/to/Spikes 6x3.png",
+	Frames=Sprite.LinearFrames(18, 1)
+}
+
+ + Returns the length of the animation in seconds. @@ -5233,7 +5744,8 @@ save yourself some time, copy this for undocumented things: Returns the Sprite's texture. - [02 Sprite.lua] Returns a Frames table consisting of iNumFrames frames lasting for a total of fSeconds seconds. This function is not a member function and should be used as Frames = Sprite.LinearFrames( 5, 2.6 ). + [02 Sprite.lua] Returns a Frames table consisting of iNumFrames frames lasting for a total of fSeconds seconds.
+ This function is not a member function and should be used as Frames = Sprite.LinearFrames( 5, 2.6 ). If sPath is nil, then unload the texture. Otherwise, load the texture at path sPath. @@ -5276,19 +5788,29 @@ save yourself some time, copy this for undocumented things: Sets the number of seconds into the animation to fSeconds. - + Sets the properties of the states of the sprite. The properties table is identical to the "Frames" table that can be put in the sprite when calling Def.Sprite.
- Example:
- {{Frame= 0, Delay= .016, {0, 0}, {.25, .25}},
- {Frame= 1, Delay= .016, {0, 0}, {.25, .25}},
- {Frame= 2, Delay= .016, {0, 0}, {.25, .25}},
- {Frame= 3, Delay= .016, {0, 0}, {.25, .25}},
- }
- Frame is optional, defaulting to 0.
- Delay is optional, defaulting to 0.
+ Example: +

+{
+	{ Frame=0, Delay=0.333, {0, 0}, {.25, .25} },
+	{ Frame=1, Delay=0.333, {0, 0}, {.25, .25} },
+	{ Frame=2, Delay=0.333, {0, 0}, {.25, .25} },
+	{ Frame=3, Delay=0.333, {0, 0}, {.25, .25} },
+}
+
+ Frame is optional, defaulting to 0.
+ Delay is optional, defaulting to 0.
The two tables are optional upper left and lower right corners of the fraction of the frame to use. The example makes the sprite only use the upper left corner of each frame.
- Simpler example:
- {{Frame= 0, Delay= .016}, {Frame= 1, Delay= .016}, {Frame= 2, Delay= .016}, {Frame= 3, Delay= .016}}
+ Simpler example: +

+{
+	{Frame=0, Delay=0.333},
+	{Frame=1, Delay=0.333},
+	{Frame=2, Delay=0.333},
+	{Frame=3, Delay=0.333}
+}
+
This example makes the sprite use the whole of each frame. @@ -5370,6 +5892,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via STATSMAN. + Returns the accumulated played StageStats. @@ -5469,7 +5994,7 @@ save yourself some time, copy this for undocumented things: Returns true if the Steps use different TimingData from the Song. - + Loads the StepsDisplay commands from the Metrics in group sMetricsGroup. @@ -5500,11 +6025,11 @@ save yourself some time, copy this for undocumented things: Returns the StyleType for this Style. - Returns a table containing the Track, XOffset, and Name of the column.
+ Returns a table containing the Track, XOffset, and Name of the column.
For example, calling GAMESTATE:GetCurrentStyle():GetColumnInfo('PlayerNumber_P1', 2) when the current - game is dance will return {Track=2, XOffset=-32, Name="Down"}.
+ game is dance will return {Track=2, XOffset=-32, Name="Down"}.
Calling GAMESTATE:GetCurrentStyle():GetColumnInfo('PlayerNumber_P1', 1) when the current - game is pump will return {Track=1, XOffset=-96, Name="DownLeft"}.
+ game is pump will return {Track=1, XOffset=-96, Name="DownLeft"}.
 Returns the draw order of the column. @@ -5563,7 +6088,7 @@ save yourself some time, copy this for undocumented things: - + Returns the of the Hold Note. @@ -5588,7 +6113,7 @@ save yourself some time, copy this for undocumented things: Returns true if the note was initiated. - + Loads the TextBanner from the specified metrics group. @@ -5600,6 +6125,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via THEME. + Returns true if the specified language exists in the current theme. @@ -5636,8 +6164,10 @@ save yourself some time, copy this for undocumented things: Returns the path of an element in the Graphics folder. - - returns three strings: BGAnimation ResolvedPath, MatchingMetricsGroup, MatchingElement. Used in LoadFallbackB in themes/_fallback/02 Other.lua. (Lua.xsd sucks) + + Returns three strings: BGAnimation ResolvedPath, MatchingMetricsGroup, MatchingElement.
+ Used in LoadFallbackB in themes/_fallback/02 Other.lua
+ Example: local path, metrics_group, element = THEME:GetPathInfoB("ScreenTitleJoin", "decorations") Returns the path of an element in the Other folder. @@ -5660,6 +6190,16 @@ save yourself some time, copy this for undocumented things: Returns the display name of the current theme. + + Returns a table of strings showing what themes the current theme falls back on.
+ For example, if the current theme is in a folder named "Home", and the "Home" theme falls back on the "default" theme, which itself falls back on the "_fallback" theme, the table would be: +

+{
+	[1]="Home",
+	[2]="default",
+	[3]="_fallback"
+}
+ Returns true if the theme has the specified metric. @@ -5684,19 +6224,24 @@ save yourself some time, copy this for undocumented things: GetBPMsAndTimes, GetStops, GetDelays, GetLabels, GetWarps, GetCombos, GetTimeSignatures, GetTickcounts, GetFakes, GetScrolls, and GetSpeeds all have two different modes.
- If false (or nothing) is the argument to these functions, they return tables of strings. The strings are numbers separated by '='.
- If the argument is true, they return tables of tables, and the inner tables contain numbers as described for each function.
- The first form is kept around and is the default for compatibility with older themes. The advantage of the second form is that you no longer need to have a bit of code in your theme to transform the string into a table of numbers before you can use it.
- Example:
- local bpmsand= timing_data:GetBPMsAndTimes()
- for i, s in ipairs(bpmsand) do
- local sand= split("=", s)
- bpmsand[i]= {tonumber(sand[1]), tonumber(sand[2])}
- end
- -- do something that looks at all the bpms and times.
- Becomes:
- local bpmsand= timing_data:GetBPMsAndTimes(true)
- -- do something that looks at all the bpms and times.
+ If false (or nothing) is the argument to these functions, they return tables of strings. The strings are numbers separated by '='.
+ If the argument is true, they return tables of tables, and the inner tables contain numbers as described for each function.
+ The first form is kept as the default to maintain compatibility with older themes. The second form can be convenient because there is no need to transform the string into a table of numbers before using it.
+ Example of first form: +

+local bpms_and_times = timing_data:GetBPMsAndTimes()
+for i, s in ipairs(bpms_and_times) do
+	local bpm_and_time = split("=", s)
+	bpms_and_times[i] = {tonumber(bpm_and_time[1]), tonumber(bpm_and_time[2])}
+end
+-- do something with the bpms and times now that they are numbers.
+
+
+ Example of second form: +

+local bpms_and_times = timing_data:GetBPMsAndTimes(true)
+-- do something with the bpms and times because they are already numbers.
+
 Returns the minimum and maximum BPM of the song in a table (in that order). @@ -5889,6 +6434,9 @@ save yourself some time, copy this for undocumented things: + + This singleton is accessible to Lua via UNLOCKMAN. + Returns true if there are any unlocks to celebrate. @@ -5977,7 +6525,7 @@ save yourself some time, copy this for undocumented things: A specific case where this is known to happen is commands that trigger on CurrentSongChanged because the music wheel clears the current song before it finishes loading if the current song is longer than the number of stages remaining. - + Sets the WorkoutGraph from the current Workout. @@ -5986,8 +6534,23 @@ save yourself some time, copy this for undocumented things: + + + StepMania's enums are exposed to Lua as global tables. Note that although the enum values start at 0, these global Lua tables are indexed starting at 1.
+ Functions that require enums as arguments will accept either the string constant or number value.
+ For example, accepts a PlayerNumber and Difficulty as arguments. + Each of these is valid way to set P1's preferred difficulty to hard:
+

+-- using strings
+GAMESTATE:SetPreferredDifficulty( "PlayerNumber_P1", "Difficulty_Hard" )
+-- using values
+GAMESTATE:SetPreferredDifficulty( 0, 3 )
+-- using global Lua tables
+GAMESTATE:SetPreferredDifficulty( PlayerNumber[1], Difficulty[4] )
+
+ Blending modes. See . @@ -6004,4 +6567,75 @@ save yourself some time, copy this for undocumented things: + + + + + The StepMania engine uses singletons internally when it needs only one instance of a class.
+ Each singleton has a class name (e.g. RageDisplay, NoteSkinManager, etc.) from the C++ engine, and a similar (but different) userdata name available to Lua (e.g. DISPLAY, NOTESKIN, etc.).
+Simple examples: +

+-- use GameState's singleton to get the current song
+local song = GAMESTATE:GetCurrentSong()
+
+-- use ScreenManager's singleton to briefly show text on-screen
+SCREENMAN:SystemMessage("hello from Lua!")
+
+ + + + + + + + + Actors are the basic building blocks used to script content for StepMania. When the player + sees and interacts with something on-screen, like a menu system or a 3D model of a dancing + character, that something is an actor.
+
+ Each of these actors is available to Lua as a function within the global Def table.
+
+ As functions, each actor accepts a table as an argument, and that table contains attributes + and commands that define how the actor will behave when rendered by the StepMania engine.
+
+ Basic examples: +

+-- Sprite, Sound, and Quad are each Actors with unique specializations
+local spr = Def.Sprite{ Texture="./path/to/image.png" }
+local snd = Def.Sound{ File="./path/to/soundeffect.ogg" }
+local sqr = Def.Quad{ InitCommand=function(self) self:xy(80, 100) end }
+
+-- common convention is to not use () with actor
+-- functions, but syntax like this is also valid
+local args = { Texture="./path/to/image.png" }
+local spr  = Def.Sprite(args)
+
+ + + + + + For players, screens are individual units of a game cycle that they interact with. Most players + understand there is a place where gameplay occurs (ScreenGameplay) that is different than the + place used to choose the next song (ScreenSelectMusic).
+
+ For scripters, screens are collections of distinct actors wrapped up in a single + ActorFrame. That ActorFrame is the "screen" that players interact with.
+
+ To be available in a theme, screens must be defined in that theme's metrics.ini file with the + desired name between square brackets like [ScreenTitleJoin] or + [ScreenPlayerOptions].
+
+ The StepMania engine defines many, many classes of screens, each with unique specialization + not directly available to Lua. For now, the screens documented here are only those with methods + available to Lua. + + +