diff --git a/Docs/Luadoc/Lua.xsl b/Docs/Luadoc/Lua.xsl index 73b9875d2c..a7cf0ea501 100644 --- a/Docs/Luadoc/Lua.xsl +++ b/Docs/Luadoc/Lua.xsl @@ -204,7 +204,7 @@ } } - + diff --git a/Docs/Luadoc/LuaDocumentation.xml b/Docs/Luadoc/LuaDocumentation.xml index 60637943ae..19ee01c14f 100644 --- a/Docs/Luadoc/LuaDocumentation.xml +++ b/Docs/Luadoc/LuaDocumentation.xml @@ -76,7 +76,7 @@ save yourself some time, copy this for undocumented things: Converts a binary formatted string to hexadecimal format. - This can be useful in conjunction with 's MD5 and SHA functions. + This can be useful in conjunction with 's MD5 and SHA functions. [02 Colors.lua] Returns the color that results from multiplying c's R, G, and B values by fBoost. @@ -85,7 +85,8 @@ save yourself some time, copy this for undocumented things: [02 Colors.lua] Modifies the brightness of the specified color. - [02 Utilities.lua] Returns true if Center 1P is being used. + [02 Utilities.lua] Returns true if the Center1Player preference is enabled during single style. Returns true when the style is double or routine, regardless of the Center1Player preference.
+ Returns false otherwise. [03 Gameplay.lua] Returns true if checkpoint judgments and tap judgments @@ -162,7 +163,7 @@ save yourself some time, copy this for undocumented things: 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. - Creates a CubicSplineN for you to use. Make sure you destroy the CubicSplineN when you're done with it, or you will have a memory leak. + Creates a CubicSplineN for you to use. Make sure you destroy the CubicSplineN when you're done with it, or you will have a memory leak. [02 Colors.lua] @@ -187,7 +188,7 @@ save yourself some time, copy this for undocumented things: 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. + [01 base.lua] to use loadfile, which itself has been overridden. [03 Gameplay.lua] @@ -271,10 +272,10 @@ save yourself some time, copy this for undocumented things: [02 Utilities.lua] Returns a path to a random song background. - + [02 Actor.lua] - + [02 Actor.lua] @@ -371,20 +372,20 @@ save yourself some time, copy this for undocumented things: 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 the current is Nonstop, Oni, or Endless.
This is effectively the same as . - + [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. - + [02 Utilities.lua] Returns true if the coin mode is set to CoinMode_Home. @@ -444,7 +445,7 @@ save yourself some time, copy this for undocumented things: loadfile is normally a core function of Lua's basic library. StepMania overrides this in - [01 base.lua] to use lua.ReadFile. + [01 base.lua] to use lua.ReadFile. [02 ActorDef.lua] Load the fallback BGA for the element that is currently being loaded. @@ -752,7 +753,7 @@ Trace(b) -- "BlendMode_AlphaMask" This way, a theme can implement a custom interactive screen for adjusting those preferences. - [01 base.lua] Alias for lua.GetThreadVariable. + [01 base.lua] Alias for lua.GetThreadVariable. Returns the current version's build date, formatted as YYYYMMDD. @@ -891,10 +892,15 @@ local playable_steps = SongUtil.GetPlayableSteps(song) 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. +

+Enum.GetName(PlayerNumber)
+Enum.Reverse(PlayerNumber)
+
+ can be condensed like
+

+PlayerNumber:GetName()
+PlayerNumber:Reverse()
+
Both x and y need to be elements of the enumerated @@ -913,12 +919,13 @@ local playable_steps = SongUtil.GetPlayableSteps(song) Returns a reverse lookup table for the enumerated type e. For example: 

-local r = PlayerNumber:Reverse()
-local n = r['PlayerNumber_P2']
+local pn1 = PlayerNumber:Reverse()['PlayerNumber_P1']
+local pn2 = PlayerNumber:Reverse()['PlayerNumber_P2']
+-- pn1 is 0
+-- pn2 is 1
- 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. + Note that the values returned from Reverse() will correspond + to the 0-based indexing from C++ and not 1-based indexing conventional to Lua. @@ -961,7 +968,11 @@ local n = r['PlayerNumber_P2'] - Creates a RageFile handle with which one can use the commands in . + Creates a RageFile handle with which one can use the commands in .
+ Example: +

+local file = RageFileUtil.CreateRageFile()
+
 @@ -1119,7 +1130,7 @@ local n = r['PlayerNumber_P2'] Sets the Actor's base Z zoom to zoom. - Sets the Actor to use the specified blend mode. + Sets the Actor to use the specified . Makes the Actor bob up and down. Can use to define different bobbing behavior. @@ -1262,7 +1273,7 @@ local n = r['PlayerNumber_P2']
The different effects use percent_through_effect in different ways. Some use it to calculate percent_between_colors with this sine wave: sin((percent_through_effect + 0.25f) * 2 * PI ) / 2 + 0.5f
Some effects check the internal bool blink_on. blink_on is true if percent_through_effect is greater than 0.5 and false if percent_through_effect is less than or equal to 0.5.

- Check the effect functions for individual explanations: , , , , , , , , , , , . + Check the effect functions for individual explanations: , , , , , , , , , , , . Set the hold_at_full part of the effect timing while leaving the others unchanged. @@ -1456,11 +1467,34 @@ end Set the Actor's rotation on the Z axis to fRotation degrees. - - + + Recursively runs the commands in cmds on the Actor's children, as well as the Actor itself.
+ Since RunCommandsRecursively belongs to StepMania's base Actor class, it is available to all specialized actors. Calling it from an ActorFrame or ActorFrameTexture can be helpful, as those specialized actors can contain children actors.
+ See and for related needs.
+ Example: +

+Def.ActorFrame{
+	Name="AF",
+	
+	Def.Sprite{ Name="sun", Texture="sun.png" },
+	
+	Def.ActorFrame{
+		Name="AF2",
+		InitCommand=function(self)
+			-- bounce() will be applied to AF2, airhorn, and catchphrase
+			self:RunCommandsRecursively( function(actor) actor:bounce() end )
+		end,
+		
+		Def.Sprite{ Name="airhorn", Texture="airhorn.png" },
+		Def.BitmapText{ Name="catchphrase", Font="Common Normal", Text="Yo!" }
+	}
+}
+
+ + [02 Actor.lua] An alternative version of . - + [02 Actor.lua] @@ -1541,7 +1575,7 @@ end 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.
- Use for the common case. + Use for the common case. Set the of the Actor according to align.
@@ -1551,7 +1585,7 @@ spr.InitCommand=function(self) self:vertalign('VertAlign_Bottom') end - Use for fractional alignment. + Use for fractional alignment. Makes the Actor vibrate violently. Can use to define different vibration behavior. @@ -1645,8 +1679,8 @@ end 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
+-- in the context of a .lua file as a screen layer
+-- this ActorFrame can be thought of as a Lua table
 local af = Def.ActorFrame{}
 
 -- add a Sprite at the next index
@@ -1665,7 +1699,7 @@ af[#af+1] = Def.BitmapText{
 return af
When actor commands like and - are used position and scale an ActorFrame, its children will position relative to the parent ActorFrame + are used to 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.
@@ -1694,6 +1728,8 @@ af[#af+1] = Def.Sprite{ return af + Likewise, if you stop drawing an ActorFrame by applying visible(false) to it, its children + will stop drawing with it.
ActorFrames can contain ActorFrames, and doing so is good design for sufficiently complex screens. @@ -1742,10 +1778,48 @@ return af Removes the specified child from the ActorFrame. - Runs the commands in cmds on the ActorFrame's children. + Runs the commands in cmds on the ActorFrame's immediate children.
+ See and for related needs.
+ Example: +

+Def.ActorFrame{
+	Name="AF",
+	InitCommand=function(self)
+		-- bounce() will be applied to sun and AF2
+		self:RunCommandsOnChildren( function(child) child:bounce() end )
+	end,
+	
+	Def.Sprite{ Name="sun", Texture="sun.png" },
+	
+	Def.ActorFrame{
+		Name="AF2",
+		Def.Sprite{ Name="airhorn", Texture="airhorn.png" },
+		Def.BitmapText{ Name="catchphrase", Font="Common Normal", Text="Yo!" }
+	}
+}
+
 - Runs the commands in cmds on the ActorFrame's leaves. + Runs the commands in cmds on the ActorFrame's leaves. Leaves are nodes in the ActorFrame tree that have no further child nodes.
+ See and for related needs.
+ Example: +

+Def.ActorFrame{
+	Name="AF",
+	InitCommand=function(self)
+		-- bounce() will be applied to sun, airhorn, and catchphrase
+		self:runcommandsonleaves( function(leaf) leaf:bounce() end )
+	end,
+	
+	Def.Sprite{ Name="sun", Texture="sun.png" },
+	
+	Def.ActorFrame{
+		Name="AF2",
+		Def.Sprite{ Name="airhorn", Texture="airhorn.png" },
+		Def.BitmapText{ Name="catchphrase", Font="Common Normal", Text="Yo!" }
+	}
+}
+
 Sets the ActorFrame's ambient light color to c. @@ -4763,11 +4837,11 @@ prev_note_name, succeeded = options:NoteSkin("cel") Returns the profile for player pn. - Returns the profile directory for the provided ProfileSlot, formatted like /Save/LocalProfiles/00000001/.
- Returns an empty string if the provided ProfileSlot does not have a loaded. + Returns the profile directory for the provided ProfileSlot, formatted like /Save/LocalProfiles/00000001/.
+ Returns an empty string if the provided ProfileSlot does not have a loaded. - Returns the number of times Song s has been played with the specified ProfileSlot. + Returns the number of times Song s has been played with the specified ProfileSlot. Returns the current stats prefix. @@ -5203,7 +5277,10 @@ Details of the event table: 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. - Returns true if a single has its NoteField centered. + Returns true if a single has its NoteField centered using the Center1Player preference.
+ Will return false if the current theme has AllowCenter1Player=false under [ScreenGameplay].
+ Notably, this can return false when the player's NoteField is visually centered, as is convention in double style or Techno_Single8.
+ Refer to the global function for a somewhat more robust check. Returns a dummy PlayerInfo for the specified index. @@ -5320,7 +5397,7 @@ Details of the event table: Returns true if anyone is still entering their name.
- (As opposed to those who are Finalized; see ) + (As opposed to those who are Finalized; see ) Returns true if Player pn is entering their name. @@ -6043,7 +6120,7 @@ local spr = Def.Sprite{ Returns true if any player has given up on the song. - Returns the EarnedExtraStage value. + Returns the EarnedExtraStage value. Returns the number of seconds played. @@ -6057,7 +6134,7 @@ local spr = Def.Sprite{ - Returns the Stage value. + Returns the Stage value. Returns the stage index. @@ -6742,7 +6819,7 @@ local bpms_and_times = timing_data:GetBPMsAndTimes(true) 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. + For example, accepts a and as arguments. Each of these is valid way to set P1's preferred difficulty to hard:

 -- using strings
@@ -6751,6 +6828,24 @@ GAMESTATE:SetPreferredDifficulty( "PlayerNumber_P1", "Difficulty_Hard" )
 GAMESTATE:SetPreferredDifficulty( 0, 3 )
 -- using global Lua tables
 GAMESTATE:SetPreferredDifficulty( PlayerNumber[1], Difficulty[4] )
+
+ It's worth pointing out that, as tables, these enums can be iterated over using or . This can be handy when you want to perform some action on every value in an enum; for example, displaying a graphic for each Difficulty. +

+-- Difficulty is a global Lua table that corresponds with
+-- the StepMania engine's Difficulty enum
+for i, diff in ipairs(Difficulty) do
+
+	-- append a file extension to create a string like
+	-- "Difficulty_Beginner.png"
+	local filename = diff .. ".png"
+
+	-- load files like "Difficulty_Beginner.png",
+	-- "Difficulty_Easy.png", etc. from the directory 
+	-- where this code is run, and offset each vertically
+	af[#af+1] = LoadActor( filename )..{
+		InitCommand=function(self) self:y( i * 100 ) end
+	}
+end
diff --git a/Docs/Luadoc/favicon.ico b/Docs/Luadoc/favicon.ico index 6334a7700d..628d01bbb5 100644 Binary files a/Docs/Luadoc/favicon.ico and b/Docs/Luadoc/favicon.ico differ