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.