How to Theme for sm-ssc: THE DOC. ________________________________________________________________________________ Table of Contents i. Introduction ii. Requirements ---------------- 1. Introduction to Concepts 1. The Raw Elements 1. Metrics 2. BGAnimations 3. Graphics 4. Fonts 5. Sounds 6. Languages 7. Scripts 8. Other 2. Screens, Classes, Managers and more 2. Elements in Detail 1. Metrics and Languages 2. BGAnimations 3. Graphics 4. Fonts 5. Sounds 6. Scripts X. Making Your First sm-ssc Theme 1. Setup 2. ________________________________________________________________________________ i. Introduction ________________________________________________________________________________ ii. Requirements In order to follow along with this guide, you will need the following: * sm-ssc (our fork of StepMania 4) * A decent text editor (syntax highlighting is a plus) * A decent graphics editor (for any graphics changes you want to make) * A decent sound editor (in case you want to edit sounds) Some of these may not apply to you (e.g. you may just want to learn how to do BGAnimations in Lua and what the differences in the metrics are). That's fine. :) Other recommended utilities will be introduced throughout this guide; they are not required if you do not wish to use them. ________________________________________________________________________________ 1. Introduction to Concepts If you are familiar with theming for another version of StepMania already, you can skim this section to see what differences exist between that version and sm-ssc. -------------------------------------------------------------------------------- 1.1 The Raw Elements A StepMania theme is comprised of multiple parts. Some of these parts are more important than others. This section briefly introduces each of the elements, explaining what they do and why they're important. More in-depth descriptions will come with each chapter. 1.1.1 Metrics The metrics (metrics.ini) contain the core elements of a theme. Most everything that has to do with StepMania's built-in types and elements will be found here. 1.1.2 BGAnimations BGAnimations are used to decorate screens. In SM4, they use Lua for BGAnims, which allows for some amazing stuff if done right. This guide won't delve too deeply into abusing BGAnimations for fun and profit (via custom coded elements), but it will be brought up later. 1.1.3 Graphics Graphics are simply that. They go along with the metrics, but can also be called from BGAnimations. Some graphics can be replaced with Lua files for more complex creations. 1.1.4 Fonts Fonts are used to draw text to the Screen. They can consist of a normal page and a stroke page, as well as the special numbers and alternate characters pages. One of the problems with SM Fonts is that they require a program to generate the required format. Both known programs are Windows-only, hindering those developing StepMania themes on Mac and Linux (unless some sort of virtualization solution is used). When you make a non-text font, you only have the choice of an image editor. Hope it has a customizable grid! (This is where Paint Shop Pro 7 beats any version of Photoshop.) 1.1.5 Sounds The Sounds folder contains both sounds that play during the use of StepMania, as well as any music your theme contains. 1.1.6 Languages Languages are where Strings that appear in the theme should be defined. Each language is represented by a two letter code, with the following examples from the default theme: en - English es - Spanish (Espanol) fr - French (Francais) it - Italian(o) de - German (Deutsch) 1.1.7 Scripts Lua Scripts were introduced in StepMania 4 (really "3.95", if you want to get technical). If you've come from theming an earlier version where they didn't exist (3.9), this folder might take some getting used to. This directory holds Lua scripts that are loaded on startup. Some scripts lay down the theming foundation, meaning that if you're crazy enough, you can rewrite everything. If you're capable of that, though, you probably don't need to read this guide. :) 1.1.8 Other The Other folder contains miscellaneous things. You generally won't need to worry about this folder unless you need to edit some uncommon files. ________________________________________________________________________________ 2. Elements in Detail Unless you are a very fast learner and can learn by looking at other people's code, you are probably wanting to know more about the elements in detail. 2.1 Metrics and Languages ______________________________________________________ These two are grouped together since they both use ini files. This means the layout of the file will contain groups, keys, and values. [Group] Key=Value { caption: Example of various .ini elements } In StepMania, most groups are Screens. The Languages folder contains strings that StepMania displays when your theme is used. Chances are, if you want to edit the text of something, there's an entry for it in one of the Language files (en.ini, usually). By leaving out a key in your custom language, you tell StepMania to look in the default language (typically en.ini) 2.2. BGAnimations ______________________________________________________________ Easily where you'll be spending the most time when making a theme, the BGAnimations provide a way for you to customize various theme parts. There are multiple names StepMania recognizes for BGAnimation folders. Some screens won't support all of these. ================================================================================ ScreenExample in - Played when the screen is transitioning in. ScreenExample background - Background of the screen. ScreenExample underlay - Shows over the background, but under decorations and overlay. ScreenExample decorations - Newly added in StepMania 4 alphas. ScreenExample overlay - Shows over everything, usually. ScreenExample out - Played when the screen is transitioning out. ScreenExample cancel - Played when the screen is canceled. ================================================================================ In StepMania 4 alphas and sm-ssc, BGAnimations are done with Lua. A sample Lua BGAnimation follows: =[begin code example]=========================================================== return Def.ActorFrame{ Def.Quad{ InitCommand=cmd(FullScreen;diffuse,color("#FFFFFF");diffusebottomedge,color("#AAAAAA");); }; }; =[end code example]============================================================= This will make a Quad (an untextured square) that fills the screen and fades from white to light grey. It is best used as a background. You can try this example out yourself by making a new folder in the Themes directory and putting this code in ScreenTitleMenu background.lua; The folder setup would end up like so: sm-ssc/ Themes/ MyCoolTheme/ BGAnimations/ ScreenTitleMenu background.lua Now open up sm-ssc and change the theme (or pass in --theme="MyCoolTheme", replacing "MyCoolTheme" with your theme's folder name), and head to the title menu. 2.3. Graphics __________________________________________________________________ The Graphics folder contains various files StepMania calls on. For example, the header and footer are found here, along with Common window icon and others. The Graphics folder is also where Decorations expects to find files to load when you use StandardDecorationFromFileOptional([MetricsName],[Filename]). 2.4. Fonts _____________________________________________________________________ StepMania fonts are a combination of images containing various characters, and an ini file that defines the font metrics, such as spacing, character widths, character mappings, and so on. Fonts are typically generated with Texture Font Generator (which is included with sm-ssc) or Bitmap Font Builder, both programs being Windows only. If you aren't on Windows, your choices are then limited to whatever image editor you can find (typically Photoshop or The GIMP). fontini.txt in the ThemerDocs folder contains a list of all the known font .ini values. The file is reprinted here: ================================================================================ [common] CapitalsOnly - If set to 1, lowercase letters are drawn with uppercase letters instead. RightToLeft - If set to 1, font will be rendered as right to left. DefaultStrokeColor - Sets default stroke color. (e.g. #00000000) [main] import - Imports a font page into the current font. (per-page) DrawExtraPixelsLeft - How many pixels to draw to the left of a character. DrawExtraPixelsRight - How many pixels to draw to the right of a character. AddToAllWidths - Adds x amount of pixels to all widths. ScaleAllWidthsBy - Scales widths by the factor specified. LineSpacing - Modifies line spacing. Top - Specifies the top of the character. (in pixels) Baseline - Specifies the baseline of the character. (in pixels) DefaultWidth - Default width for a glyph. AdvanceExtraPixels - Rudimentary way to control letter spacing TextureHints - An alternative to throwing the TextureHints in the filename. (general commands) MAP - Maps a keyword to a frame number. (e.g. map up=0) RANGE - Defines a Unicode range to use. LINE - (e.g. Line 1=ABCDEFGH) ================================================================================ 2.5. Sounds ____________________________________________________________________ sm-ssc can load Lua files as music, allowing for conditional music/sounds. conditional_music.txt in the ThemerDocs folder explains it in more detail with code examples. 2.6. Scripts ___________________________________________________________________ Scripts allow you to define functions which can then be referenced in Metrics and BGAnimations. Scripts can also store values and do other nice things, some of which is outside of the scope of this guide.