AJ's StepMania Theming Corner for 11/7/2007 CVS

[AJ 187]

Hello, and welcome to AJ's StepMania Theming Corner.

This is a column released with every new CVS version of StepMania that details the changes made as they relate to themers.

// Contents //
1. Mission Statement
2. Letter from the Editor
3. Changes from July 26th, 2007 CVS
4. From the Vault: Profile Stats via Lua
5. Useful Resources

// Mission Statement //
Why did I decide to do this? History repeats itself.

Zhek @ DDREI on July 20, 2004
http://forums.ddrei.com/viewtopic.php?p=13835#13835

"My problem is that no one comments new changes to metrics. Metrics aren't code. It's **** simple stuff. It's just when someone does something stupid like rename something, not report it when they compile a release, and it breaks everything because of a name change. If they commented changes, the work load would be drastically reduced in size. Changing things isn't really all that hard, usually SM warns you that something is missing. It's when functionality or something assine (sp) like a name change is added where it starts annoying me. Warn me about it with the updates, no problem."

kurisu @ the official SM forums on September 17, 2007:
"The entire theme mechanics were changed on us, with almost little or no
documentation; tons of new features are being added in without us even getting to know about them, and are broken accidentally by the time we even learn of them."

As you can see from the above two quotes, history repeats itself.
Three years down the line, I'd hope that a themer doesn't say something like this again. That's why I started the Theming Corner.

// Letter from the Editor //
You won't find the Mission Statement in every issue, just to let you know.
Most issues will have a Letter from the Editor, the changes as they affect you, and possibly something theming-related From the Vault.

That being said...

// Changes from July 26th, 2007 CVS //
These changes possibly affect you. I tend to list the updates that affect themers, but I also include important StepMania-wide updates if they're about things people have raised complaints over, such as the input/output bug in SMO.

The general format is [change // author]. These changes are pulled from #stepmania on irc.freenode.net, which is the CVS log dump. If you wish to talk about StepMania development, join #stepmania-devs on the same network.

* Added GetDate for LunaHighScore // vdl
You can now get the date for a certain high score via Lua.

* Default to DirectSound-sw for now // Glenn Maynard
This should make it so you don't have to change the sound driver in Windows by default in order for SM to sound good.

* hidden becomes deprecated // Glenn Maynard
hidden is deprecated and replaced with visible. They operate in about the same way, i.e. hidden,false = visible,true. My theory on why this was done: objects generally display by default.

* Added GetSurvivalSeconds for HighScore // vdl
You can now get the survive time for a certain high score via Lua.

* Memory Card Lua states // vdl
"MemoryCardState type for lua, MEMCARDMAN:GetCardState for lua"

* ScreenSelectProfile added // vdl
I believe that this was when ScreenSelectProfile was officially added to SM.
vdl says "should be used before style selection like ScreenProfileLoad", but
I've been able to use it after style selection with no known problems.

* MovieTexture_FFMpeg can be used in Xbox build // vdl
One can assume that this means you can use movies in StepManiaX now. :)

* NoteSkinManager Lua bindings // Steve Checkowav
These bindings are used in ScreenInstructions to display note graphics. Much better than the old way of "oh great, we have a new noteskin, time to change ScreenInstructions again."

* Number of RainbowColors changeable. // Steve Checkoway
NumRainbowColors is now available in [BitmapText].

* StepMania Online fixes. // Steve Checkoway, SMO Team
Steve fixed the OffCommand and text display errors.

* BitmapText Attributes // Steve Checkoway
This allows BitmapText objects to be colored in the middle of a string, among other neat things.

* BitmapText multibyte string length Lua binding // Steve Checkoway
"Add lua binding for multibyte string length." Used with the Attribute system above for easier placement of attributes.

* StepsSelected message changed to StepsChosen message // Chris Danford

* Allow BitmapText:settext to use alternate text // Glenn Maynard

* ScreenOptionsToggleSongs added // Glenn Maynard
Supposedly this would let you toggle what songs show up.

* GetNextScreen changed to GetNextScreenName // Chris Danford

* m_bJukeboxUsesModifiers now does something // vdl
Previously, it didn't. In Lua, use GAMESTATE:SetJukeboxUsesModifiers(true/false).

* "Move percent formatting into PlayerStageStats" // Chris Danford
This resulted in a new metric, [Common] PercentScoreDecimalPlaces. It also caused the PercentageDisplay section to be removed from the metrics.

* SetTransformFromWidth added to ActorScroller // AJ Kelly
The sister function to SetTransformFromHeight, no idea why this wasn't in SM before.

* More Profile Lua bindings // AJ Kelly
GetNumToasties, GetTotalTapsAndHolds, GetTotalJumps, GetTotalJumps, GetTotalRolls, GetTotalMines, GetTotalHands. These do as they say on the tin.
This month's From the Vault will show you how to abuse these.

* Addition of missing keys on ScreenTextEntry // vdl

* Ability to sort songs by Length // AJ Kelly
I had been sitting on the code to do this for about a year, so I figured it might as well get put into SM.

* Use Enums for param in RadarValues:GetValue // Chris Danford
If you're one of the few people who uses GetValue (myself), this means you don't use integers anymore for referencing the values. Yay for consistency!

* Use enum types in Lua methods on Workout // Chris Danford
Basically the same thing as above, except applied to the Workout Lua bindings.

Whew, that was really long.

// From the Vault //
From the Vault is a section where I let themers know about some stuff that they may not have known could be done.

As explained above, this release's From the Vault is about getting Profile Stats via Lua.

Why would you want to do this? You could display profile stats on the new ScreenSelectProfile, for instance.

The overview of how this works:
1) Get a profile
2) Process the stats
3) Display them.

Step 1: Getting a profile.
For this example, I won't be using ScreenSelectProfile since it requires a lot of Lua code to be made by the user. The screen's a bit TOO flexible.

You'll be working with PROFILEMAN (ProfileManager) and Profile. To make things simple, we'll just load stats from the Machine Profile.

In your Lua BGAnimation file, do the following:

-- start code
local sysProfile = PROFILEMAN:GetMachineProfile();
local toasties = sysProfile:GetNumToasties();

LoadFont( "","_zeroesthree" )..{
Text="";
InitCommand=cmd(x,SCREEN_CENTER_X;y,SCREEN_CENTER_ Y;shadowlength,0;playcommand,"Set");
SetCommand=function(self)
self:settext( string.format("Toasties: %i", toasties) );
end;
};
-- end code

The above code assumes you're adding it to an existing ActorFrame. If you aren't, put a return before LoadFont, making the first line

return LoadFont( "","_blaster" )..{

In any case, this is likely to confuse you, so let's go into the code.

local sysProfile = PROFILEMAN:GetMachineProfile();
This line of code makes a local variable called "sysProfile" and sets it to the machine profile.

local toasties = sysProfile:GetNumToasties();
This makes a local variable called "toasties" and fills it with the number of Toasties that sysProfile has gotten.

LoadFont( "","_zeroesthree" )..{
We then create a BitmapText object with the _zeroesthree font.

Text="";
There's no text by default.

InitCommand=cmd(x,SCREEN_CENTER_X;y,SCREEN_CENTER_ Y;shadowlength,0;playcommand,"Set"); We set the x position to SCREEN_CENTER_X, which is derived from [Common] ScreenWidth. The y position gets sent to SCREEN_CENTER_Y, derived from [Common] ScreenHeight. No shadow is set, and then we use something called playcommand.

playcommand lets you define your own commands. It's up to you to run them, however, since StepMania likely does not have handling code for your command.
Yes, you could call existing commands such as On, but that rarely happens.

Anyways, the above code tells us to play the "Set" command, which means there will be a matching SetCommand:

SetCommand=function(self)
self:settext( string.format("Toasties: %i", toasties) );
end;

Oh god he's got us making Lua functions now.
This is what StepMania actually does when you wrap things in a cmd().

Anyways, function(self) just lets us know we're making a function that takes in itself (an Actor) as an argument, allowing us to mess with it.

From there...
self:settext( string.format("Toasties: %i", toasties) );

settext is self-explanatory, it lets you change the text of a BitmapText object. What may not be obvious is string.format(). This is a Lua function that allows you to format strings. In this case, there are two arguments.

The first is the string to be displayed. You'll notice there's an %i in there, which, if you run this code, is missing. It actually gets replaced by a number. This number is the value of toasties, which we set before.

%i is actually a token, and whenever you place one in a string.format() string, it expects another argument to the function. If you know C/C++, this should be nothing new to you.

If you don't, here are a list of common tokens:
%i - integer (whole number)
%f - float (floating point number)
%s - string (text)

If all went well, you'll now be able to show how many Toasties the system
profile has gotten.

// Useful Resources //
At the end of every Theming Corner, you'll find a list of links that can be useful to themers.

The SMTheming Wiki: http://kki.ajworld.net/wiki/
Tooting my own horn here, as usual. The SMTheming Wiki is a good resource for learning about StepMania theming. It also plays host to online versions of AJ's StepMania Theming Corner, which include formatting so that things such as examples are less confusing!

Lua.xml: http://stepmania.sf.net/Lua.xml
Something you may not have known about is that SMCVS can output an XML file that lists all of the Lua bindings as well as Enumerated Types and other neat information.

Steve Checkoway and myself try to update the documentation as much as we can, and if you've idled in #stepmania, you'll notice I left out a lot of commits to LuaDocumentation.xml that were made. That file is sadly not included with general user versions of SMCVS, but you can always grab a copy from the repository.

If you DO have the other files (Lua.xsd, Lua.xsl, LuaDocumentation.xml), here's a fun tip. Instead of waiting for the online copy to be updated, generate Lua.xml yourself!

Just pass --ExportLuaInformation to StepMania (via command line or shortcut), and you'll get a Lua.xml in the root of the SM directory. Move it to where you have LuaDocumentation.xml, Lua.xsd, and Lua.xsl, then open Lua.xml in a web browser to see what you can use. Some things have documentation, some don't.

edit: the Wiki version of this is now available.
edit 2: the files that aid in working with Lua.xml are now available here. Follow the above instructions to learn how to use them.

[kurisu]

Epic post: You have every bit of my respect, admiration, and thanks for posting this.

Seriously, the time it had to have taken you to get this list up had to be major... many thanks from me, and I am sure all of the people who are trying to learn sm4 coding. I will try this weekend to study and at least begin to toy around with it. ^_^

[AJ 187]

Originally Posted by kurisu

Seriously, the time it had to have taken you to get this list up had to be major

Not really; I had modified the example from work on DWI SM4, I watch #stepmania every day (the worst part in compiling the changelog was to go back through logs to find what was changed since it had been so long), and that's about it. :v

[kurisu]

Still, it takes time...

<offtopic> sm3.9 will NOT compile for me.. so im in a bad mood.. oh joy! </offtopic>

[AJ 187]

The following is being posted as an addendum to the November 7th, 2007 issue.

The only new thing the 11/21/2007 release adds for themers afaik:

add OldPageIndex and NewPageIndex to *SwitchPage messages - Chris Danford
I'll take the blame for this one, guys. Asked for this for the DWI theme. :x

//From the Page//
Here's how you use it, courtesy of Chris:

FYI, the messages and parameters are:
Message msg("PreSwitchPage");
msg.SetParam( "OldPageIndex", (int)oldPage );
msg.SetParam( "NewPageIndex", (int)newPage );
and
Message msg("PostSwitchPage");
msg.SetParam( "NewPageIndex", (int)newPage );

[hampsterblade]

AJ how do u do banner masks in SM4?

[AJ 187]

A long and complicated process, so I'm just going to steal vdl's code.

You need to make an ActorFrame that draws by ZPosition for this.

Def.ActorFrame {
	InitCommand=function(self) 
		self:SetDrawByZPosition(true);
	end;
	children = {
		Def.ActorProxy {
			BeginCommand=function(self) 
				local banner = SCREENMAN:GetTopScreen():GetChild('Banner'); 
				banner:ztestmode('ZTestMode_WriteOnPass'); 
				self:SetTarget(banner); 
			end;
			OnCommand=cmd(x,SCREEN_CENTER_X+160+430;y,SCREEN_CENTER_Y-128;z,8.11;rotationy,-20;rotationz,0.6;decelerate,0.75;addx,-430);
			OffCommand=cmd(accelerate,0.75;addx,430);
		};
		LoadActor(THEME:GetPathG(Var 'LoadingScreen','banner mask')) .. {
                	InitCommand=cmd(x,SCREEN_CENTER_X-320+444;y,SCREEN_CENTER_Y-240+222;z,8.1);
			OnCommand=cmd();
			OffCommand=cmd();
		};
	};
};

[shakesoda]

How do you mask the musicwheel?

I've even been looking at vdl's code in the itg2 theme and don't get it. :/

[Tio]

does stepmania accept 3d models in music wheel?

[GRIM.657]

I dont see why it wouldnt, but how would you put a 3D model on the wheel anyway?

erm, i guess something like the MusicWheel grades or whatever could in theory use a 3D model, but idk...

How do you mask the musicwheel?

I've even been looking at vdl's code in the itg2 theme and don't get it. :/

The same way you would mask a banner, which is the same way you would mask anything else :P

(tbh the only way i've done it is by making the 'real' music wheel invisible, and using an ActorProxy to call the musicwheel from the lua file, rather than from metrics.ini, then you just mask that like you mask any other actor)