Tutorials:Beginning Theming/Chapter 1

Welcome to Chapter 1 of Tutorials:BeginningTheming.

Hopefully you've completed Before You Begin before heading into here. If not, go read it unless you're sure you know what tools you need and that you understand some basic concepts.

Setting Up Your Development Environment
This section assumes you've installed StepMania 3.9 already as well as your needed tools. If you have not done so, now would be a pretty good time to do that.

There are at least two ways to begin theming. This section will describe two of them. Before we go into that, though, there are a few things you should do, as they will help you greatly during theme development.

There may be a common error you will run into after enabling the popups. This will be discussed in Chapter 4.
 * 1) Play in Windowed mode. The reason for this is that you will get popups explaining any errors you may get. When playing in Windowed mode, it's easier to debug a theme as well.
 * 2) If you've played in Windowed mode before, open up StepMania.ini in the Data folder and see if there's anything in . If there is something after the equals sign, remove it. This will cause those popups to return, helping you polish the theme.

Copying Default
The first method to begin theming is to copy over the default theme folder. This gives you a tangible base of things to work with, but is not recommended for releasing a theme, as there may be elements left over that you don't use at all. For a beginner, however, this is the preferred starting method, as a number of elements are already available for editing.

Starting from Scratch
While this method may be harder for beginners, it will get easier as time goes on. An added bonus is that you don't have all the clutter of the default theme included.

This method is as simple as creating a new directory and a Metrics.ini file.

With both methods explained, we can now look at the Metrics.

Metrics.ini and Commands
Metrics.ini defines a bulk of the hard-coded objects available to you in StepMania (such as MusicWheel), as well as the Screens available to you (like ScreenSelectMusic). If this is your first time looking at Metrics.ini, you may be daunted, as the default Metrics.ini is about 146KB and contains quite a bit of items. This section will only deal with Commands, as Screens and the elements housed in them will be dealt with in Chapter 3. Commands Commands are how things get done in StepMania. They can control things like position, color, and more. A list of available commands is available in the Commands category. However, some basics will be covered in this section. Object Commands When dealing with Metrics.ini, some objects will have Commands. The two most often used Commands are OnCommand and OffCommand. These gets triggered when the screen is called and when the screen is finished, respectively.

An example of OnCommand and OffCommand is below: Icon1OnCommand=addx,-640;sleep,0.20;decelerate,0.3;addx,640 Icon1OffCommand=bouncebegin,0.5;zoomy,0 This specific example deals with Icon1 on ScreenSelectStyle. Don't worry about what all of those commands mean just yet. Positioning At the very minimum, objects will have coordinates. To keep things simple, we will focus on X and Y (although Z is available as well).

In order to set an object's X and Y coordinates, you place  or , use a comma, and then place a number. For example, Commands are separated by the semicolon like in programming languages. Since StepMania's commands are issued in Lua (even in 3.9), this is to be expected. When dealing with Metrics.ini, certain objects will have entries for their X and Y values. You do not need to set X and Y in the general command. Continuing with Icon1 on ScreenSelectStyle: Icon1X=60 Icon1Y=84 Icon1 will appear at 60 X and 84 Y. This is near the top left corner of the screen. Generally, StepMania themers code for 640x480, so keep that in mind when choosing values. There are times when you can go above 640 or 480, but they are rare (SelectDifficulty is a prime example). Now, let's look back at the On and Off commands for Icon1.

Icon1OnCommand=addx,-640;sleep,0.20;decelerate,0.3;addx,640 Icon1OffCommand=bouncebegin,0.5;zoomy,0 You'll notice a command called. This operates similar to just setting x, however, it will take the current value of x (as set in Icon1X) and add -640 to it. and  also exist. Time With positioning figured out, that only leaves four more commands to explain in the above example. This section will knock out three of those four.

In StepMania, much like real life, time is moving forward. In order to animate objects, we must take into consideration the commands StepMania gives us for timing. The above example uses,  , and. is the simplest of the three. It will wait however many seconds before issuing the next command in the queue. For instance,  will wait one second before executing the next command. and its brother  slow down and speed up code execution. In the above example,  is used. This code will move the object 640 pixels to the left in the span of 3/10ths of a second. However, instead of moving in a smooth fashion, the object will move slower as it reaches its destination. does the opposite. Think of them like you would the Brake and Boost modifiers for your arrows.

and  are a bit trickier to explain. These two will cause the object to bounce before or after the command. In the OffCommand above, the object will bounce before zooming to 0 on the y axis. (We're not there yet though!) is the most often used time command. Unlike the other time based commands listed above, it will linearly perform the next action. There is no deceleration, no acceleration, no bouncing. It just happens. Zooming and Other Things objects can do The only command out of the Icon1 example that was not covered yet was. As was hinted at above, this will make the object disappear on the y axis. and  also exist.

However, when it comes to making objects "do things," you're not limited to zooming. This section will cover making items appear and disappear to begin with. It is possible to make objects fade out using a combination of a time command and something known as. What this command does is sets the object's alpha level (transparency) to whatever value you give it. Let's rewrite Icon1 to make it fade out when ScreenSelectMusic goes away: Icon1OffCommand=linear,0.5;diffusealpha,0 This command uses  to make the object fade to nothing within the span of half a second. You may be wondering what the upper value of  is, as there could be many ways to express it. Much like other arguments to  (which we will cover shortly), the max value is 1. This gives you anywhere from 0 to 1. If you are having a hard time grasping this, think of it as a percentage, with 1 being equal to 100%, 0 being equal to 0%, and 0.5 being equal to 50%.

Effects Now, if you've seen the default theme's ScreenSelectStyle, you've noticed that the currently focused icon glows, and when you switch between options, it stops glowing. This is handled through Effects. Let's look at the Icon Gain and LoseFocus commands: IconGainFocusCommand=glowshift;effectperiod,0.5 IconLoseFocusCommand=stopeffect You'll notice no Time commands here. Effects don't operate using normal time commands. They use effect time commands instead, which are slightly different. When the icon gains focus,  goes into effect. Without matching s, it will default to glowing white. takes the place of the time commands, but uses the same type of system. In this example, the icon will glow white for half of a second.

As soon as the icon loses focus, all of the effects stop running.