AJ's StepMania Theming Corner for 1/4/2008 CVS

[AJ 187]

Sorry I'm a bit late on this one.

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. Letter from the Editor
2. Changes from November 21st, 2007 CVS
3. From the Vault: SongBPMDisplay on ScreenGameplay
4. Useful Resources

// Letter from the Editor //
Well, a day or so after the release, I decide to actually write this, instead of having it prepared beforehand, as I didn't expect a release to happen for a few more weeks.

In any case, welcome to the new year, and I hope that as the year goes on, more and more people attempt to theme for the newest CVS builds. From what I've seen and heard from people, there's a few projects in the works already.

With there not being so many changes, this is going to be a pretty sparse update aside from the From the Vault section.

// Changes from November 21st, 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 movies playing too fast or changing every beat.

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.

* Fix both combo/miss labels being shown at once // AJ Kelly
Oh hey here's one of my commits maybe this will fix it once and for all

* Reset Sprite state. Make movies skip the first update. // Steve Checkoway
Fixes background movies playing too quickly at first.

* Fix GetNoteRowsPerMeasure() returning note rows per beat. // Steve Checkoway
[see below change for implications]

* Change random movies every 4 measures. // Steve Checkoway
This combined with the TimingData.h change fixes random movies switching every beat instead of every four measures.

* Only play a key sound for a press, not a release. // Steve Checkoway
Keysounds are working better now which means that making themes for the beat gametype won't be as much of a waste of time as it was before. :D

// From the Vault //
And with that last comment comes the impetus for this issue's 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.

This time around, I'm going to show you how to get a BPMDisplay on ScreenGameplay that actually updates with the song, like in IIDX and some other games.

The overview:
1) Make sure you have everything you need
2) Throw in SongBPMDisplay in the overlay
3) Profit

Step 1: Getting Ready.
This will be simple, as it's likely everything's set up for you already.

SongBPMDisplay uses the same font as BPMDisplay, so if you already have a BPMDisplay font (such as BPMDisplay bpm 5x3.png), you're halfway there.

The other half is having a "ScreenGameplay overlay" folder in BGAnimations. There's likely to be one there already, as in the default theme, it's used to display the score frames.

Step 2: Throwing it in.
Now that we've defined everything, we get to put the SongBPMDisplay in the overlay. Since SongBPMDisplay is derived from BPMDisplay, here is the minimum amount of work you have to do to get it in your Gameplay screen:

1) Go to BGAnimations/ScreenSelectMusic overlay/default.lua and copy the Def.BPMDisplay section into BGAnimations/ScreenGameplay overlay/default.lua right after this line:

return Def.ActorFrame {

It should now look something like this:

return Def.ActorFrame {
Def.BPMDisplay {
File=THEME:GetPathF("BPMDisplay", "bpm");
Name="BPMDisplay";
InitCommand=cmd(horizalign,right;y,SCREEN_CENTER_Y-134;shadowlength,0;);
OnCommand=cmd(stoptweening;x,SCREEN_CENTER_X-160-SCREEN_WIDTH*0.6;bounceend,0.5;addx,SCREEN_WIDTH*0 .6);
OffCommand=cmd(bouncebegin,0.5;addx,-SCREEN_WIDTH*0.6);
SetCommand=function(self) self:SetFromGameState() end;
CurrentSongChangedMessageCommand=cmd(playcommand," Set");
CurrentCourseChangedMessageCommand=cmd(playcommand ,"Set");
};

You can copy the _bpm label layer too if you want.

The important change is this one, however:

Def.BPMDisplay {

becomes

Def.SongBPMDisplay {

At this point you can futz around with the commands and make everything work the way you want it to, which brings us to Step 3.

Step 3: Profit.
As you can see, we're done.

That was one of the simplest things ever, since 99% of the work was done for you, all you really had to do was type four letters. :D

Now if you really want to have some fun, realize that BPMDisplay is a derivative class of BitmapText and...

Well, that's for another time, when I actually test out my crazy hypothesis.

I'll give you a hint though:

BitmapText::GetText()
BitmapText::SetText()

Might want to crack open Lua.xml and look at that :)

// 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 few 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.

The Wiki version is available where you'd expect it: right here.