From 4635973799511de2008897e9afecb4f214f4aedd Mon Sep 17 00:00:00 2001 From: quietly-turning Date: Thu, 25 Jun 2020 05:10:25 -0400 Subject: [PATCH] add grouping attr to Class elements in LuaDoc These "grouping"s aren't part of the spec in Docs/Luadoc/Lua.xsd, so they won't appear when Lua.xml is viewed in a web browser, but can still be used by external API doc applications until ExportLuaInformation is improved. --- Docs/Luadoc/LuaDocumentation.xml | 167 ++++++++++++++++++++----------- 1 file changed, 111 insertions(+), 56 deletions(-) diff --git a/Docs/Luadoc/LuaDocumentation.xml b/Docs/Luadoc/LuaDocumentation.xml index 3532861279..46e085c629 100644 --- a/Docs/Luadoc/LuaDocumentation.xml +++ b/Docs/Luadoc/LuaDocumentation.xml @@ -980,7 +980,7 @@ local n = r['PlayerNumber_P2'] - + Actor is the base class containing common methods that all specialized actor classes inherit. For example, GetX is a method belonging to Actor, @@ -1611,7 +1611,7 @@ local n = r['PlayerNumber_P2'] Sets the x and y location of the Actor in one command. - + 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) @@ -1756,7 +1756,7 @@ return af Sets the vanishing point for the ActorFrame. - + Creates the ActorFrameTexture. @@ -1779,7 +1779,7 @@ return af Sets the Texture's name to sName. - + Adds a texture to the ActorMultiTexture. Returns the number of texture units. @@ -1799,7 +1799,7 @@ return af Sets a TextureMode on the specified index. - + The list of quad states is used to determine which animation state is used for each quad. The offset is added to the AMV's current state, and the resulting state is used. @@ -1948,7 +1948,7 @@ self:SetDrawState{First= 3, Num= 4} Sets the texture at from the file path path. - + Returns the target of the ActorProxy. @@ -1956,7 +1956,7 @@ self:SetDrawState{First= 3, Num= 4} Sets the ActorProxy target to a. - + Returns the scroller's current item. @@ -2043,7 +2043,7 @@ self:SetDrawState{First= 3, Num= 4} Sets the scroller's transform function from fItemWidth. - + 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. @@ -2123,7 +2123,7 @@ Def.Sound{ Returns the name of the architecture in use. - + Returns true if the Banner is currently scrolling. @@ -2167,7 +2167,7 @@ Def.Sound{ - + 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, @@ -2288,7 +2288,7 @@ Def.BitmapText{ Wrap the unzoomed text at iWidth pixels. If you or by x and you want the text wrapped at width, then you should use wrapwidthpixels(width/x). - + Returns the text that is currently set at the exact moment you call it. This is likely only going to be useful in an Update command. @@ -2357,7 +2357,7 @@ Def.BitmapText{ Returns the number of characters available. - + Loads the ComboGraph commands from the Metrics in group sMetricsGroup. @@ -2365,7 +2365,7 @@ Def.BitmapText{ Sets the values of the ComboGraph using the specified StageStats and PlayerStageStats. - + Loads the ControllerStateDisplay from the specified GameController. @@ -2459,7 +2459,7 @@ Def.BitmapText{ Returns true if the Course is a ranking course. - + Sets the CourseContentsList from the GameState. @@ -2597,13 +2597,13 @@ Def.BitmapText{ 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. @@ -2677,7 +2677,7 @@ Def.BitmapText{ - + Returns the index of the last banner loaded. @@ -2718,7 +2718,7 @@ Def.BitmapText{ See . - + Sets the StepsDisplayList from the GameState. @@ -3268,7 +3268,7 @@ end Unjoins player pn. - + Loads the GradeDisplay commands from the Metrics in group sMetricsGroup. @@ -3276,7 +3276,7 @@ end Sets the GradeDisplay to show Grade g. - + Loads the GraphDisplay commands from the Metrics in group sMetricsGroup. @@ -3284,7 +3284,7 @@ end Sets the values of the GraphDisplay using the specified StageStats and PlayerStageStats. - + Sets the GrooveRadar values for Player pn to empty. @@ -3295,7 +3295,7 @@ end Sets the GrooveRadar values for Player pn to the specified (floating point) values in the table. - + Returns two tables representing the tips and alternate tips in the HelpDisplay. @@ -3370,7 +3370,7 @@ end Returns the rank of the highest score for name in the list. Returns 0 if there is no score for name in the list. (returns 1 if name has the top score, 2 if name has the second place score, and so on) - + Loads the HoldJudgment for the specified MultiPlayer. @@ -3389,7 +3389,7 @@ end 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. @@ -3479,12 +3479,12 @@ end Sets whether logging of messages is enabled. If log is true, all messages that pass through Broadcast (from the engine for from the theme or from anywhere else), will be logged with Trace. - + Sets the width of the MeterDisplay to fWidth. - + Returns the model's default animation. @@ -3508,7 +3508,7 @@ end Returns the number of states the Model has. - + Loads the ModIconRow of Player pn from the Metrics in group sMetricsGroup. @@ -3716,12 +3716,12 @@ end Returns true if this row forces one choice on all players. - + Sets the PaneDisplay from the GameState. - + Sets the PercentageDisplay from the specified PlayerState and PlayerStageStats. @@ -4631,7 +4631,7 @@ prev_note_name, succeeded = options:NoteSkin("cel") 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. @@ -4865,7 +4865,7 @@ prev_note_name, succeeded = options:NoteSkin("cel") Reloads the texture. - + Loads the metrics for this RollingNumbers from sGroupName. @@ -4873,7 +4873,7 @@ prev_note_name, succeeded = options:NoteSkin("cel") Sets the target number to f. - + 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 @@ -5001,19 +5001,19 @@ Details of the event table: [02 Other.lua] Gets a string from the current Screen in the current language. - + - + Returns the current . - + Returns the current StageStats. - + 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. @@ -5066,7 +5066,7 @@ Details of the event table: Pauses or unpauses the game, depending on the value of bPause. - + Returns the LifeMeter. @@ -5119,7 +5119,7 @@ Details of the event table: Broadcasts a system message. - + Returns true if Player pn backspaced successfully. @@ -5147,18 +5147,18 @@ Details of the event table: Gets the currently selected letter of Player pn. - + Returns the number of active players. - + - + - + - + Returns true if all active players are on the last options row. @@ -5175,12 +5175,12 @@ Details of the event table: Returns the specified OptionRow. - + Returns true if we are going to PlayerOptions. - + Continues to the next screen. @@ -5188,7 +5188,7 @@ Details of the event table: Returns true if there is a profile that can be loaded. - + Continues to the next screen. @@ -5196,12 +5196,12 @@ Details of the event table: Returns true if there is a profile that can be saved. - + Returns player pn's current selected item as an integer. - + Returns false if the options list is already open or the UseOptionsList metric is false. @@ -5221,7 +5221,7 @@ Details of the event table: [02 StageMods.lua] Sets up modifiers for non-course modes. - + Tells the screen to go to the previous screen. @@ -5239,7 +5239,7 @@ Details of the event table: • -2: unjoin the player, unlock their MemoryCard, and unmount their MemoryCard - + 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 @@ -5305,7 +5305,7 @@ local args = { - + Tells the screen to go to the previous screen. @@ -5319,7 +5319,7 @@ local args = { 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. - + @@ -5708,7 +5708,7 @@ local args = { Returns the warp destination length. - + 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.
@@ -5994,7 +5994,7 @@ local spr = Def.Sprite{ Returns true if the Steps use different TimingData from the Song. - + Loads the StepsDisplay commands from the Metrics in group sMetricsGroup. @@ -6113,7 +6113,7 @@ local spr = Def.Sprite{ Returns true if the note was initiated. - + Loads the TextBanner from the specified metrics group. @@ -6525,7 +6525,7 @@ local bpms_and_times = timing_data:GetBPMsAndTimes(true) A specific case where this is known to happen is commands that trigger on CurrentSongChanged because the music wheel clears the current song before it finishes loading if the current song is longer than the number of stages remaining. - + Sets the WorkoutGraph from the current Workout. @@ -6583,4 +6583,59 @@ SCREENMAN:SystemMessage("hello from Lua!") + + + + + + + Actors are the basic building blocks used to script content for StepMania. When the player + sees and interacts with something on-screen, like a menu system or a 3D model of a dancing + character, that something is an actor.
+
+ Each of these actors is available to Lua as a function within the global Def table.
+
+ As functions, each actor accepts a table as an argument, and that table contains attributes + and commands that define how the actor will behave when rendered by the StepMania engine.
+
+ Basic examples: +

+-- Sprite, Sound, and Quad are each Actors with unique specializations
+local spr = Def.Sprite{ Texture="./path/to/image.png" }
+local snd = Def.Sound{ File="./path/to/soundeffect.ogg" }
+local sqr = Def.Quad{ InitCommand=function(self) self:xy(80, 100) end }
+
+-- common convention is to not use () with actor
+-- functions, but syntax like this is also valid
+local args = { Texture="./path/to/image.png" }
+local spr  = Def.Sprite(args)
+
+ + + + + + For players, screens are individual units of a game cycle that they interact with. Most players + understand there is a place where gameplay occurs (ScreenGameplay) that is different than the + place used to choose the next song (ScreenSelectMusic).
+
+ For scripters, screens are collections of distinct actors wrapped up in a single + ActorFrame. That ActorFrame is the "screen" that players interact with.
+
+ To be available in a theme, screens must be defined in that theme's metrics.ini file with the + desired name between square brackets like [ScreenTitleJoin] or + [ScreenPlayerOptions].
+
+ The StepMania engine defines many, many classes of screens, each with unique specialization + not directly available to Lua. For now, the screens documented here are only those with methods + available to Lua. + + +