diff --git a/Docs/Luadoc/Lua.xml b/Docs/Luadoc/Lua.xml index bec2e01f46..cbcd85d52b 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 @@ + + + + + + diff --git a/Docs/Luadoc/LuaDocumentation.xml b/Docs/Luadoc/LuaDocumentation.xml index 765ecc3aaa..d063c59940 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,25 +785,6 @@ 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. -