lua docs

ComboGraph, MusicWheel, NoteField, Player, WheelBase, HoldNoteScore, SortOrder, TapNoteScore, WheelItemDataType

Themes/_fallback/docs/Actors/ComboGraph.luadoc

@@ -1,2 +1,42 @@
 --- Combo Graph class
--- @classmod ComboGraph
+--[[
+        The ComboGraph will display the combos for a score on a graph.
+        Although, it's a bit more integrated with PlayerStageStats than one might desire...
+        A ComboGraph can be created directly with `Def.ComboGraph`
+        Its primary use is in ScreenEvaluation
+--]]
+-- @classmod ComboGraph
+
+
+--- Initialize the ComboGraph using the given metrics group.
+-- This is the way to customize a ComboGraph via metrics, creating a section as [groupName]. Children components are also loaded from Theme Graphics.
+-- The children components are Actors named `<groupName> Backing` `<groupName> NormalCombo` `<groupName> MaxCombo`
+-- Another child component that must be a @{BitmapText} is `<groupName> ComboNumber`
+-- In metrics.ini, the metrics that must be defined are `BodyWidth` and `BodyHeight` under the section [groupName]
+-- @tparam string metricsGroup The group to load from metrics.ini and Theme Graphics.
+-- @return self
+function ComboGraph:Load(metricsGroup)
+end
+
+--- Load combo data into the ComboGraph from @{StageStats} and @{PlayerStageStats}.
+-- The StageStats is only used to determine the length of the song in question.
+-- Otherwise, this is the same as SetWithoutStageStats.
+-- @see ComboGraph:SetWithoutStageStats
+-- @tparam StageStats stageStats The StageStats for the current score
+-- @tparam PlayerStageStats playerStageStats The PlayerStageStats for the current score
+-- @return self
+function ComboGraph:Set(stageStats, playerStageStats)
+end
+
+--- Load combo data into the ComboGraph from @{PlayerStageStats}.
+-- @tparam PlayerStageStats playerStageStats The PlayerStageStats for the current score
+-- @tparam number lastSecond The last second of the current score, which is usually the length of the song.
+-- @return self
+function ComboGraph:SetWithoutStageStats(playerStageStats, lastSecond)
+end
+
+--- Destroys all children which were loaded via Load, so you can use Load again.
+-- If you fail to do this before running Load, then you can unintentionally orphan the children or have too many children.
+-- @return self
+function ComboGraph:Clear()
+end

Themes/_fallback/docs/Actors/MusicWheel.luadoc

@@ -1,2 +1,89 @@
 --- Music Wheel class
--- @classmod MusicWheel
+--[[
+        This class inherits methods from the @{WheelBase} class. A MusicWheel is the structure responsible for 
+        allowing the user to scroll through songs and make a selection to play.
+        The easiest way to acquire the existing MusicWheel on a screen is `SCREENMAN:GetTopScreen():GetMusicWheel()`
+--]]
+-- @classmod MusicWheel
+
+--- Change the @{SortOrder} for the MusicWheel. This is the equivalent of pressing UpDown UpDown then making a choice.
+-- @tparam string SortOrder A @{SortOrder} passed as a string
+-- @treturn bool Whether or not the change was successful
+function MusicWheel:ChangeSort(SortOrder)
+end
+
+--- Get the name of the current group being hovered.
+-- @treturn string The name of the group being hovered.
+function MusicWheel:GetSelectedSection()
+end
+
+--- Deprecated method, since Roulette/Random has been mostly removed.
+-- @treturn bool True if the MusicWheel is currently in Roulette mode (spinning endlessly)
+function MusicWheel:IsRouletting()
+end
+
+--- Instantly warp the MusicWheel to the first found instance of the given Song. This will fail if the Song has been filtered out for some reason.
+-- @tparam Song Song The @{Song} which you want to select.
+-- @treturn bool True if the Song can be selected
+function MusicWheel:SelectSong(Song)
+end
+
+--- Use super-search to filter the MusicWheel
+-- This can be used to search for specific metadata for all Charts in the current Game.
+-- Multiple metadata fields can be searched by separating them with a `;`. When given multiple fields to search, any results must match all fields.
+-- For example, to search for both the title and artist, `title=xxx;artist=yyy`
+-- If the search returned no results, then the previous successful search is executed again.
+-- Valid metadata fields: `artist=` `author=` `title=` `subtitle=` `group=` `charter=` `stepper=` `pack=` `ck=`
+-- @tparam string searchString The full search you want to run
+-- @return nil
+function MusicWheel:SongSearch(searchString)
+end
+
+--- Remove the search filter from the MusicWheel
+-- @return nil
+function MusicWheel:ReloadSongList()
+end
+
+--- Move the MusicWheel a given number of Songs. This may fail if the wheel is locked.
+-- @tparam int amount The number of Songs to move. When nil, move 0. When negative, go in the other direction.
+-- @return nil
+function MusicWheel:Move(amount)
+end
+
+--- Move the MusicWheel a given number of Songs. This may fail if the wheel is locked.
+-- @tparam int amount The number of Songs to move. When nil, move 0. When negative, go in the other direction.
+-- @treturn string The @{WheelItemDataType} of the resulting Song that the Move landed on.
+function MusicWheel:MoveAndCheckType(amount)
+end
+
+--- Filter the current MusicWheel results using a given table of ChartKeys.
+-- The MusicWheel is filtered to contain only charts which match the given keys.
+-- @tparam {string,...} chartkeys A table of chartkeys
+-- @return nil
+function MusicWheel:FilterByStepKeys(chartkeys)
+end
+
+--- Filter the current MusicWheel results using two given tables of ChartKeys.
+-- The MusicWheel is filtered to contain only the charts which match the first list of keys. If none are given, then only exclude any charts that match the second list.
+-- @tparam {string,...} requireChartkeys A list of chartkeys to require match.
+-- @tparam {string,...} excludeChartkeys A list of chartkeys to exclude from the results.
+-- @return nil
+function MusicWheel:FilterByAndAgainstStepKeys(requireChartkeys, excludeChartkeys)
+end
+
+--- Set the state of the Common Pack Filter for Multiplayer
+-- Turning this on filters out any packs that you do not have in common with other players in the lobby.
+-- @tparam bool toggle Turn the Common Pack Filter on or off.
+-- @treturn bool The new state of the Common Pack Filter
+function MusicWheel:SetPackListFiltering(toggle)
+end
+
+--- Get the current list of @{Song}s in the MusicWheel, after all filtering.
+-- @treturn {Song,...} List of Songs
+function MusicWheel:GetSongs()
+end
+
+--- Get the list of @{Song}s in the given group for the current @{SortOrder}, after all filtering.
+-- @treturn {Song,...} List of Songs. If the group does not exist, then this is nil.
+function MusicWheel:GetSongsInGroup(group)
+end

Themes/_fallback/docs/Actors/NoteField.luadoc

@@ -1,2 +1,105 @@
 --- NoteField class
--- @classmod NoteField
+--[[
+        This class contains the components responsible for displaying notes in gameplay.
+        The simplest way to get the NoteField in gameplay is `SCREENMAN:GetTopScreen():GetChild("PlayerP1"):GetChild("NoteField")`
+--]]
+-- @classmod NoteField
+
+
+--- Set the function that executes every time the player steps.
+-- The callback function has the parameters `(intColumn, TapNoteScore)`.
+-- The callback function returns 2 values, `intColumn, TapNoteScore`
+-- The point of passing and returning these values is to be able to redirect them.
+-- @see NoteField:Step
+-- @tparam func callback A function to execute later
+-- @return nil
+function NoteField:set_step_callback(callback)
+end
+
+--- Set the function that executes every time the player presses a column.
+-- The callback function has the parameter `(intColumn)`
+-- The callback function returns 1 value, `intColumn`
+-- The point of passing and returning the column is to be able to redirect column numbers.
+-- @see NoteField:set_pressed
+-- @tparam func callback A function to execute later
+-- @return nil
+function NoteField:set_set_pressed_callback(callback)
+end
+
+--- Set the function that executes every time the player tapped on a note.
+-- The callback function has the parameters `(intColumn, TapNoteScore, boolBright)`
+-- The callback function returns 3 values, `intColumn, TapNoteScore, boolBright`
+-- The point of passing and returning these values is to be able to redirect them.
+-- The boolBright parameter is usually true when the current combo has passed BrightGhostComboThreshold
+-- @see NoteField:did_tap_note
+-- @tparam func callback A function to execute later
+-- @return nil
+function NoteField:set_did_tap_note_callback(callback)
+end
+
+--- Set the function that executes every time the player taps on the head of a hold or roll.
+-- The callback function has the parameters `(intColumn, HoldNoteScore, boolBright)`
+-- The callback function returns 3 values, `intColumn, HoldNoteScore, boolBright`
+-- The point of passing and returning these values is to be able to redirect them.
+-- The boolBright parameter is usually true when the current combo has passed BrightGhostComboThreshold
+-- @see NoteField:did_hold_note
+-- @tparam func callback A function to execute later
+-- @return nil
+function NoteField:set_did_hold_note_callback(callback)
+end
+
+--- Run the Step action on a given column and @{TapNoteScore}.
+-- Note that this does not trigger the callback function that can be set from Lua.
+-- @tparam int column The 1-indexed column to step on, starting from the left.
+-- @tparam TapNoteScore tns The TapNoteScore to emulate on the given column.
+-- @return nil
+function NoteField:step(column, tns)
+end
+
+--- Run the SetPressed action on a given column.
+-- Note that this does not trigger the callback function that can be set from Lua.
+-- Setting a column to pressed will set it as unpressed at the next update as long as the button is not held by the player.
+-- @tparam int column The 1-indexed column to set as pressed, starting from the left.
+-- @return nil
+function NoteField:set_pressed(column)
+end
+
+--- Run the DidTapNote action on a given column and @{TapNoteScore}.
+-- Note that this does not trigger the callback function that can be set from Lua.
+-- @tparam int column The 1-indexed column to trigger DidTapNote, starting from the left.
+-- @tparam TapNoteScore tns The TapNoteScore to emulate on the given column.
+-- @tparam bool bright Set to true to signal that the bright state should be active. Bright is usually enabled for combos above BrightGhostComboThreshold.
+-- @return nil
+function NoteField:did_tap_note(column, tns, bright)
+end
+
+--- Run the DidHoldNote action on a given column and @{HoldNoteScore}.
+-- Note that this does not trigger the callback function that can be set from Lua.
+-- @tparam int column The 1-indexed column to trigger DidHoldNote, starting from the left.
+-- @tparam HoldNoteScore hns The HoldNoteScore to emulate on the given column.
+-- @tparam bool bright Set to true to signal that the bright state should be active. Bright is usually enabled for combos above BrightGhostComboThreshold.
+-- @return nil
+function NoteField:did_hold_note(column, hns, bright)
+end
+
+--- Get the @{NoteColumnRenderer}s for each column.
+-- Using these, you can manipulate each individual column in the NoteField.
+-- @treturn {NoteColumnRenderer,...} A table of NoteColumnRenderers starting from the left
+function NoteField:get_column_actors()
+end
+
+--- Toggle showing the beat bars in the NoteField board (behind the notes).
+-- Ordinarily, beat bars become visible if the metric ShowBeatBars is enabled. Setting this to true overrides that.
+-- Turning this off while the metric is turned on, however, does not force the bars off.
+-- The beat bars are typically visible for each measure, but can be more often depending on your metrics.
+-- See BarMeasureAlpha, Bar4thAlpha, Bar8thAlpha, Bar16thAlpha in metrics.
+-- @tparam bool state True when you want the bars to be on.
+function NoteField:show_beat_bars(state)
+end
+
+--- Toggle showing the interval bars in the NoteField board (behind the notes).
+-- The interval bars are simply bars that are aligned to each half second in time.
+-- Their use is to be aligned to the intervals of notes that are passed to the difficulty calculator, so they are not practical otherwise.
+-- @tparam bool state True when you want the bars to be on.
+function NoteField:show_interval_bars(state)
+end

Themes/_fallback/docs/Actors/Player.luadoc

@@ -1,2 +1,29 @@
 --- Player control class
--- @classmod Player
+--[[
+        This controls the user interaction with the current chart being played in gameplay.
+        One way to retrieve the Player in gameplay is `SCREENMAN:GetTopScreen():GetChild("PlayerP1")`
+        The Player owns the @{NoteField}, Combo, Tap Judgments, and Hold Judgments, among other things.
+        Most of these children can be found via GetChild by name, such as "Combo", "Judgment", "NoteField"
+--]]
+-- @classmod Player
+
+--- Set the Lifebar to a new given value.
+-- Ordinarily, this value must be between 0 and 1, but the max is actually determined by metric LifeMultiplier.
+-- @tparam number value The new value to set the Lifebar to.
+-- @return self
+function Player:SetLife(value)
+end
+
+--- Set the Lifebar to a new value by changing it by a given amount.
+-- The value given to this function is scaled by Preference LifeDifficultyScale, which is the Life Difficulty setting.
+-- @tparam number amount The amount to change the Player life.
+-- @return self
+function Player:ChangeLife(amount)
+end
+
+--- Retrieve the @{TimingData} that the Player is relying on.
+-- Normally, this is just the TimingData of the current @{Steps}.
+-- This is like an alias of `GAMESTATE:GetCurrentSteps():GetTimingData()`
+-- @treturn TimingData The TimingData of the currently playing Steps.
+function Player:GetPlayerTimingData()
+end

Themes/_fallback/docs/Actors/WheelBase.luadoc

@@ -1,2 +1,59 @@
 --- Selection Wheel base class
--- @classmod WheelBase
+--[[
+        This is the base class for other wheel classes such as @{MusicWheel} and @{RoomWheel}
+        The easiest way to acquire the existing Wheel on a screen is `SCREENMAN:GetTopScreen():GetMusicWheel()`
+--]]
+-- @classmod WheelBase
+
+--- Move the wheel a given amount of choices in some direction.
+-- @tparam int amount Amount to move. Nil does no move. Negative goes in the other direction.
+-- @return self
+function WheelBase:Move(amount)
+end
+
+--- Retrieve the @{WheelItemBase} at a given index.
+-- This does not retrieve an arbitrarily far wheel item, but actually the visible item.
+-- Every time a movement is made on the Wheel, the data behind each WheelItem is switched to another WheelItem.
+-- For example, the highest allowed index to pass is (NUM_WHEEL_ITEMS-1) which comes from the metrics.ini definition for the Wheel implementation you are using (NumWheelItems).
+-- @tparam int index Index for the WheelItem to retrieve.
+-- @treturn WheelItemBase The WheelItem at the given index. Returns nil and throws an error if the index is not valid.
+function WheelBase:GetWheelItem(index)
+end
+
+--- Query whether or not the Wheel is settled. The Wheel is settled if it is not moving or locked.
+-- @treturn bool True if the wheel is not moving.
+function WheelBase:IsSettled()
+end
+
+--- Query whether or not the Wheel is locked. The Wheel is locked when a selection was just made or roulette just finished.
+-- @treturn bool True if the wheel is locked.
+function WheelBase:IsLocked()
+end
+
+--- Set the current open section on the Wheel.
+-- This is usually used to change the opened folder remotely.
+-- @tparam string sectionName The name of a group or section, depending on the @{SortMode}
+-- @return self
+function WheelBase:SetOpenSection(sectionName)
+end
+
+--- Get the current index of the hovered item in all of the data loaded in the Wheel. This is not restricted by NumWheelItems.
+-- @treturn int Index of the currently hovered item.
+function WheelBase:GetCurrentIndex()
+end
+
+--- Get the number of items in the data loaded in the Wheel. This is not restricted by NumWheelItems.
+-- This may include all Songs and all Group items.
+-- @treturn int Count of items in the Wheel.
+function WheelBase:GetNumItems()
+end
+
+--- Get the @{WheelItemDataType} of the currently hovered WheelItem.
+-- @treturn WheelItemDataType The type of the currently hovered WheelItem.
+function WheelBase:GetSelectedType()
+end
+
+--- Rebuild the WheelItems to refresh the visual data.
+-- @return self
+function WheelBase:RebuildWheelItems()
+end

Themes/_fallback/docs/Enums/HoldNoteScore.luadoc

@@ -0,0 +1,12 @@
+--- HoldNoteScore enum
+--[[
+        HoldNoteScore is the enum representing the score for a hold or roll.
+        The simplest way to pass them around in Lua is by directly referencing as a string.
+        Valid HoldNoteScores:
+            "HoldNoteScore_None" (The lack of a score)
+            "HoldNoteScore_LetGo" (The hold was dropped after hitting the head)
+            "HoldNoteScore_Held" (The hold was completed)
+            "HoldNoteScore_Missed" (The hold was completely missed, including the head)
+
+--]]
+-- @classmod HoldNoteScore

Themes/_fallback/docs/Enums/SortOrder.luadoc

@@ -0,0 +1,27 @@
+--- SortOrder enum
+--[[
+        SortOrder is the enum representing a SortOrder for Songs.
+        The simplest way to pass them around in Lua is by directly referencing as a string.
+        Valid SortOrders:
+            "SortOrder_Group"
+            "SortOrder_Title"
+            "SortOrder_BPM"
+            "SortOrder_TopGrades"
+            "SortOrder_Artist"
+            "SortOrder_Genre"
+            "SortOrder_ModeMenu"
+            "SortOrder_Length"
+            "SortOrder_DateAdded"
+            "SortOrder_Favorites"
+            "SortOrder_Overall"
+            "SortOrder_Stream"
+            "SortOrder_Jumpstream"
+            "SortOrder_Handstream"
+            "SortOrder_Stamina"
+            "SortOrder_JackSpeed"
+            "SortOrder_Chordjack"
+            "SortOrder_Technical"
+            "SortOrder_Author"
+            "SortOrder_Ungrouped"
+--]]
+-- @classmod SortOrder