From 91bf61a178195f87101b6ed4754e6f1f283fe569 Mon Sep 17 00:00:00 2001 From: quietly-turning Date: Thu, 25 Jun 2020 04:55:13 -0400 Subject: [PATCH] update LuaDocs for Classes Fix, clarify, and expand prose in LuaDocumentation.xml for classes made available to Lua. Add elements for DeviceList, InputList, Quad, and SongMeterDisplay to Lua.xml. --- Docs/Luadoc/Lua.xml | 8 + Docs/Luadoc/LuaDocumentation.xml | 680 ++++++++++++++++++++++++------- 2 files changed, 538 insertions(+), 150 deletions(-) diff --git a/Docs/Luadoc/Lua.xml b/Docs/Luadoc/Lua.xml index ff7beb128f..3da459c121 100644 --- a/Docs/Luadoc/Lua.xml +++ b/Docs/Luadoc/Lua.xml @@ -783,6 +783,8 @@ + + @@ -1044,6 +1046,8 @@ + + @@ -1534,6 +1538,8 @@ + + @@ -1870,6 +1876,8 @@ + + diff --git a/Docs/Luadoc/LuaDocumentation.xml b/Docs/Luadoc/LuaDocumentation.xml index 1f668554e9..8de4ee0a4a 100644 --- a/Docs/Luadoc/LuaDocumentation.xml +++ b/Docs/Luadoc/LuaDocumentation.xml @@ -974,6 +974,11 @@ 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.
@@ -1034,19 +1039,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. @@ -1073,13 +1079,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. @@ -1109,13 +1115,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. @@ -1138,10 +1147,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. @@ -1150,7 +1160,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. @@ -1168,13 +1180,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. @@ -1277,8 +1293,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. @@ -1295,15 +1311,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). @@ -1330,13 +1348,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. @@ -1360,7 +1384,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"). @@ -1399,13 +1424,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. @@ -1465,7 +1490,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. @@ -1482,8 +1509,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. @@ -1575,6 +1605,66 @@ save yourself some time, copy this for undocumented things: + + 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. @@ -1582,14 +1672,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. @@ -1800,17 +1890,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. @@ -1946,11 +2038,30 @@ save yourself some time, copy this for undocumented things: - 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. @@ -2012,10 +2123,10 @@ save yourself some time, copy this for undocumented things: - + Loads the background from an UnlockEntry. - + Loads the banner from an UnlockEntry. @@ -2050,6 +2161,40 @@ 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.
@@ -2445,6 +2590,12 @@ 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. @@ -2657,7 +2808,7 @@ save yourself some time, copy this for undocumented things: Return the localized string representation of st. - + Returns a table of all selectable games. @@ -2726,15 +2877,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. @@ -2754,7 +2907,7 @@ save yourself some time, copy this for undocumented things: Returns the current for the specified . - + Returns the current . @@ -3229,6 +3382,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. @@ -3297,7 +3455,7 @@ 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. @@ -3589,12 +3747,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:
@@ -3603,15 +3761,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.
 @@ -3766,7 +3934,7 @@ save yourself some time, copy this for undocumented things: - + Returns true if step attacks or random attacks are enabled. @@ -3840,11 +4008,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.
@@ -4107,9 +4282,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. + + @@ -4445,6 +4624,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 . @@ -4580,7 +4764,7 @@ 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. @@ -4683,29 +4867,101 @@ save yourself some time, copy this for undocumented things: + + 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. @@ -4738,6 +4994,8 @@ 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 . @@ -4777,19 +5035,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. @@ -4817,7 +5075,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. @@ -4847,8 +5105,8 @@ 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. @@ -4887,6 +5145,12 @@ save yourself some time, copy this for undocumented things: Returns the number of active players. + + + + + + Returns true if all active players are on the last options row. @@ -4962,18 +5226,76 @@ 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
+}
+
 @@ -4990,26 +5312,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). @@ -5021,13 +5349,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. @@ -5224,8 +5556,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. @@ -5370,6 +5702,25 @@ save yourself some time, copy this for undocumented things: + + 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. @@ -5386,7 +5737,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. @@ -5429,19 +5781,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. @@ -5656,11 +6018,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. @@ -5719,7 +6081,7 @@ save yourself some time, copy this for undocumented things: - + Returns the of the Hold Note. @@ -5795,8 +6157,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. @@ -5819,6 +6183,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. @@ -5843,19 +6217,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). @@ -6148,6 +6527,7 @@ save yourself some time, copy this for undocumented things: +