From dea29375d0c5c87939b9c49b26b798b0e11787a7 Mon Sep 17 00:00:00 2001 From: Barinade Date: Sun, 4 Aug 2024 22:19:19 -0500 Subject: [PATCH] lua docs ComboGraph, MusicWheel, NoteField, Player, WheelBase, HoldNoteScore, SortOrder, TapNoteScore, WheelItemDataType --- .../_fallback/docs/Actors/ComboGraph.luadoc | 42 ++++++- .../_fallback/docs/Actors/MusicWheel.luadoc | 89 ++++++++++++++- Themes/_fallback/docs/Actors/NoteField.luadoc | 105 +++++++++++++++++- Themes/_fallback/docs/Actors/Player.luadoc | 29 ++++- Themes/_fallback/docs/Actors/WheelBase.luadoc | 59 +++++++++- .../_fallback/docs/Enums/HoldNoteScore.luadoc | 12 ++ Themes/_fallback/docs/Enums/SortOrder.luadoc | 27 +++++ .../_fallback/docs/Enums/TapNoteScore.luadoc | 19 ++++ .../docs/Enums/WheelItemDataType.luadoc | 16 +++ 9 files changed, 393 insertions(+), 5 deletions(-) create mode 100644 Themes/_fallback/docs/Enums/HoldNoteScore.luadoc create mode 100644 Themes/_fallback/docs/Enums/SortOrder.luadoc create mode 100644 Themes/_fallback/docs/Enums/TapNoteScore.luadoc create mode 100644 Themes/_fallback/docs/Enums/WheelItemDataType.luadoc diff --git a/Themes/_fallback/docs/Actors/ComboGraph.luadoc b/Themes/_fallback/docs/Actors/ComboGraph.luadoc index 4fd329c87b..c043441f56 100644 --- a/Themes/_fallback/docs/Actors/ComboGraph.luadoc +++ b/Themes/_fallback/docs/Actors/ComboGraph.luadoc @@ -1,2 +1,42 @@ --- Combo Graph class --- @classmod ComboGraph \ No newline at end of file +--[[ + 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 ` Backing` ` NormalCombo` ` MaxCombo` +-- Another child component that must be a @{BitmapText} is ` 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 diff --git a/Themes/_fallback/docs/Actors/MusicWheel.luadoc b/Themes/_fallback/docs/Actors/MusicWheel.luadoc index 9f01b6b911..d368bdba3d 100644 --- a/Themes/_fallback/docs/Actors/MusicWheel.luadoc +++ b/Themes/_fallback/docs/Actors/MusicWheel.luadoc @@ -1,2 +1,89 @@ --- Music Wheel class --- @classmod MusicWheel \ No newline at end of file +--[[ + 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 diff --git a/Themes/_fallback/docs/Actors/NoteField.luadoc b/Themes/_fallback/docs/Actors/NoteField.luadoc index ce634f4b6c..986a46d395 100644 --- a/Themes/_fallback/docs/Actors/NoteField.luadoc +++ b/Themes/_fallback/docs/Actors/NoteField.luadoc @@ -1,2 +1,105 @@ --- NoteField class --- @classmod NoteField \ No newline at end of file +--[[ + 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 diff --git a/Themes/_fallback/docs/Actors/Player.luadoc b/Themes/_fallback/docs/Actors/Player.luadoc index 60b4451959..bf066963fa 100644 --- a/Themes/_fallback/docs/Actors/Player.luadoc +++ b/Themes/_fallback/docs/Actors/Player.luadoc @@ -1,2 +1,29 @@ --- Player control class --- @classmod Player \ No newline at end of file +--[[ + 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 \ No newline at end of file diff --git a/Themes/_fallback/docs/Actors/WheelBase.luadoc b/Themes/_fallback/docs/Actors/WheelBase.luadoc index c27f85411c..29f0a44054 100644 --- a/Themes/_fallback/docs/Actors/WheelBase.luadoc +++ b/Themes/_fallback/docs/Actors/WheelBase.luadoc @@ -1,2 +1,59 @@ --- Selection Wheel base class --- @classmod WheelBase \ No newline at end of file +--[[ + 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 diff --git a/Themes/_fallback/docs/Enums/HoldNoteScore.luadoc b/Themes/_fallback/docs/Enums/HoldNoteScore.luadoc new file mode 100644 index 0000000000..0bb1d8866c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/Themes/_fallback/docs/Enums/SortOrder.luadoc b/Themes/_fallback/docs/Enums/SortOrder.luadoc new file mode 100644 index 0000000000..67366fc0ea --- /dev/null +++ b/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 \ No newline at end of file diff --git a/Themes/_fallback/docs/Enums/TapNoteScore.luadoc b/Themes/_fallback/docs/Enums/TapNoteScore.luadoc new file mode 100644 index 0000000000..c24c845b50 --- /dev/null +++ b/Themes/_fallback/docs/Enums/TapNoteScore.luadoc @@ -0,0 +1,19 @@ +--- TapNoteScore enum +--[[ + TapNoteScore is the enum representing the score for a tap. + The simplest way to pass them around in Lua is by directly referencing as a string. + Valid TapNoteScores: + "TapNoteScore_None" (The lack of a score) + "TapNoteScore_HitMine" + "TapNoteScore_AvoidMine" (Did not hit a mine) + "TapNoteScore_CheckpointMiss" (deprecated) + "TapNoteScore_Miss" + "TapNoteScore_W5" (Bad) + "TapNoteScore_W4" (Good) + "TapNoteScore_W3" (Great) + "TapNoteScore_W2" (Perfect) + "TapNoteScore_W1" (Marvelous) + "TapNoteScore_CheckpointHit" (deprecated) + +--]] +-- @classmod TapNoteScore \ No newline at end of file diff --git a/Themes/_fallback/docs/Enums/WheelItemDataType.luadoc b/Themes/_fallback/docs/Enums/WheelItemDataType.luadoc new file mode 100644 index 0000000000..19a0e761e2 --- /dev/null +++ b/Themes/_fallback/docs/Enums/WheelItemDataType.luadoc @@ -0,0 +1,16 @@ +--- WheelItemDataType enum +--[[ + WheelItemDataType is the enum representing the type for a WheelItem. + The simplest way to pass them around in Lua is by directly referencing as a string. + Valid WheelItemDataTypes: + "WheelItemDataType_Generic" + "WheelItemDataType_Section" + "WheelItemDataType_Song" + "WheelItemDataType_Roulette" + "WheelItemDataType_Random" + "WheelItemDataType_Portal" + "WheelItemDataType_Course" + "WheelItemDataType_Sort" + "WheelItemDataType_Custom" +--]] +-- @classmod WheelItemDataType \ No newline at end of file