AJ Kelly
226 lines
9.9 KiB
Plaintext
226 lines
9.9 KiB
Plaintext
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. |