Create Themes

This information refers mostly to StepMania 4 and StepMania 5 theming.

Resources

Tips and Tricks

• Useful information and warnings are in Logs\log.txt.
• In Preferences.ini, set ShowLogOutput=1 then restart StepMania. In the Window version, this will cause a log window to appear. In other versions, the log contents will be written to the console.
• In StepMania 4, hold F3 then press 'R' to reload theme metrics and textures.

Changes from 3.9 to 4.0

These are the elements whose names have changed from 3.9 to 4.0.

XML file format

Example:

<ActorFrame>
	<children>
		<Actor 
			File="hello.png" 
			InitCommand="x,SCREEN_CENTER_X;y,SCREEN_CENTER_Y"
		/>
	<children>
</ActorFrame>

• "default.xml" can be used instead of "BGAnimation.ini"
• "[element name].xml" can be a BGAnimation or Graphics element without being placed in a directory, or you can create a directory "[element name]" that contains default.xml

Numbers

• The Numbers/ directory has been merged into Fonts/ directory. You'll need to move all numbers files and rename them the files as well. File names typically changed like this: Numbers/Combo 5x3.png -> Fonts/Combo numbers 5x3.png

Renamed elements

• OptionsCursor cursor -> ScreenOptions cursor
• ScreenOptions item -> OptionRow item

Screen Positions

X and Y positions can now be expressions. You can use the following constants to position elements:

• SCREEN_CENTER_X
• SCREEN_CENTER_Y
• SCREEN_WIDTH
• SCREEN_HEIGHT
• SCREEN_LEFT
• SCREEN_RIGHT
• SCREEN_TOP
• SCREEN_BOTTOM

Example: SCREEN_CENTER_X - 100 (a little to the left of the center of the screen)

ScreenSelectMaster

NumIconParts and NumPreviewParts have been removed. This is no longer necessary now that theme elements in Graphics can use .Lua files to make complex combinations.

Language support

Language .ini files file names now use ISO language codes ("en.ini","es.ini") instead of full-text names ("english.ini", "spanish.ini").

Metric names

The judgements have been renamed:

.actor Files

Support for .actor files was removed.

[Actor]
File=blah.png
BaseRotationX=60
OnCommand=pulse

<Actor
   File="blah.png"
   BaseRotationX="60"
   OnCommand="pulse"
/>

return LoadActor("blah.png")..{
    InitCommand=cmd(rotationx,60),
    OnCommand=cmd(pulse)
}

.sprite Files

Support for .sprite files was removed.

[Sprite]
Texture=blah 2x1.png
Frame0000=0
Delay0000=0.12
Frame0001=1
Delay0001=0.12

<Sprite
     Texture="blah 2x1.png"
     Frame0000="0"
     Delay0000="0.12"
     Frame0001="1"
     Delay0001="0.12"
/>

return Def.Sprite {
     Texture="blah 2x1.png",
     Frame0000=0,
     Delay0000=0.12,
     Frame0001=1,
     Delay0001=0.12
}

.model Files

Support for .model files was removed.

[Model]
Meshes=meshes.txt
Materials=materials.txt
Bones=bones.txt

<Model
   Meshes="meshes.txt"
   Materials="materials.txt"
   Bones="bones.txt"
/>

return Def.Model {
   Meshes="meshes.txt",
   Materials="materials.txt",
   Bones="bones.txt"
}

Where are the data files saved?

SM4 saves the data files on a per-user basis. Where that is depends on your operating system:

 * Windows (XP): %appdata%\StepMania 4
 * Mac OS X: /Users/<username>/Library/Preferences/StepMania 4
 * *Linux*: /home/<username>/.stepmania4/

Additionally, one can make a blank file called Portable.ini in the main StepMania folder to allow the data files to save there instead. (Useful for making StepMania portable on a USB stick.)

Theme Q&A

How do I get the song title to display on the gameplay screen?

In "ScreenGameplay overlay", you can have:

<BitmapText
    Font="common normal"
    Text="@GAMESTATE:GetCurrentSong():GetDisplayFullTitle()"
/>

How do I display decimal numbers in the menu timer?

In SM 4, you define the format of the timer string. Check [MenuTimer] Text1FormatFunction and Text2FormatFunction. You want something like:

Text1FormatFunction=function(secs) return string.format("0.0f",secs) end