Known properties
Known properties refer to properties of simfiles and their charts that the current stable version of StepMania actively uses. These are the properties that simfile exposes as attributes on simfile and chart objects. They are also the only properties that StepMania’s built-in editor will preserve when saving a simfile; unknown properties are liable to be deleted if saved by the StepMania editor.
When working with known properties, you should prefer to use attributes (e.g.
sim.title
, chart.stepstype
) rather than indexing into the
underlying dictionary (e.g. sim['TITLE']
, chart['STEPSTYPE']
).
While these are functionally equivalent in many cases, attributes generally
behave closer to how StepMania interprets simfiles:
If a property is missing from the simfile, accessing the attribute returns None instead of throwing a
KeyError
. StepMania generally treats missing properties as if they had an empty or default value, so it’s nice to be able to handle this case without having to catch exceptions everywhere.StepMania supports a few legacy aliases for properties, and attributes make use of these aliases when present. For example, if a simfile contains a
FREEZES
property instead of the usualSTOPS
,sim.stops
will use the alias in the backing dictionary (both for reads and writes!), whereassim['STOPS']
will throw aKeyError
. This lets you write cleaner code with fewer special cases for old simfiles.Attributes are implicitly spell-checked: misspelling a property like
sim.artistranslit
will consistently raise anAttributeError
, and may even be flagged by your IDE depending on its Python type-checking capabilities. By contrast, reading fromsim['ARTISTRANSLIT']
will generally raise the more vagueKeyError
exception, and writing to such a field would create a new, unknown property in the simfile, which is probably not what you wanted. Furthermore, your IDE would have no way to know the string property is misspelled.
With that said, there are legitimate use cases for indexing. String keys are
easier when you need to operate on multiple properties generically, and they’re
the only option for accessing “unknown properties” like numbered
BGCHANGES
and properties only used by derivatives of StepMania.
When dealing with property string keys, consider using the .get
method
from the underlying dictionary to handle missing keys gracefully.
What are the known properties?
These are the known properties for simfiles:
String key |
Attribute |
SMSimfile |
SSCSimfile |
---|---|---|---|
TITLE |
title |
✓ |
✓ |
SUBTITLE |
subtitle |
✓ |
✓ |
ARTIST |
artist |
✓ |
✓ |
TITLETRANSLIT |
titletranslit |
✓ |
✓ |
SUBTITLETRANSLIT |
subtitletranslit |
✓ |
✓ |
ARTISTTRANSLIT |
artisttranslit |
✓ |
✓ |
GENRE |
genre |
✓ |
✓ |
CREDIT |
credit |
✓ |
✓ |
BANNER |
banner |
✓ |
✓ |
BACKGROUND |
background |
✓ |
✓ |
LYRICSPATH |
lyricspath |
✓ |
✓ |
CDTITLE |
cdtitle |
✓ |
✓ |
MUSIC |
music |
✓ |
✓ |
OFFSET |
offset |
✓ |
✓ |
BPMS |
bpms |
✓ |
✓ |
STOPS |
stops |
✓ |
✓ |
FREEZES 1 |
stops |
✓ |
|
DELAYS |
delays |
✓ |
✓ |
TIMESIGNATURES |
timesignatures |
✓ |
✓ |
TICKCOUNTS |
tickcounts |
✓ |
✓ |
INSTRUMENTTRACK |
instrumenttrack |
✓ |
✓ |
SAMPLESTART |
samplestart |
✓ |
✓ |
SAMPLELENGTH |
samplelength |
✓ |
✓ |
DISPLAYBPM |
displaybpm |
✓ |
✓ |
SELECTABLE |
selectable |
✓ |
✓ |
BGCHANGES |
bgchanges |
✓ |
✓ |
ANIMATIONS 1 |
bgchanges |
✓ |
✓ |
FGCHANGES |
fgchanges |
✓ |
✓ |
KEYSOUNDS |
keysounds |
✓ |
✓ |
ATTACKS |
attacks |
✓ |
✓ |
VERSION |
version |
✓ |
|
ORIGIN |
origin |
✓ |
|
PREVIEWVID |
previewvid |
✓ |
|
JACKET |
jacket |
✓ |
|
CDIMAGE |
cdimage |
✓ |
|
DISCIMAGE |
discimage |
✓ |
|
PREVIEW |
preview |
✓ |
|
MUSICLENGTH |
musiclength |
✓ |
|
LASTSECONDHINT |
lastsecondhint |
✓ |
|
WARPS |
warps |
✓ |
|
LABELS |
labels |
✓ |
|
COMBOS |
combos |
✓ |
|
SPEEDS |
speeds |
✓ |
|
SCROLLS |
scrolls |
✓ |
|
FAKES |
fakes |
✓ |
And these are the known properties for charts:
String key |
Attribute |
SMChart |
SSCChart |
---|---|---|---|
STEPSTYPE |
stepstype |
✓ |
✓ |
DESCRIPTION |
description |
✓ |
✓ |
DIFFICULTY |
difficulty |
✓ |
✓ |
METER |
meter |
✓ |
✓ |
RADARVALUES |
radarvalues |
✓ |
✓ |
NOTES |
notes |
✓ |
✓ |
NOTES2 1 |
notes |
✓ |
|
CHARTNAME |
chartname |
✓ |
|
CHARTSTYLE |
chartstyle |
✓ |
|
CREDIT |
credit |
✓ |
|
MUSIC |
music |
✓ |
|
BPMS |
bpms |
✓ |
|
STOPS |
stops |
✓ |
|
DELAYS |
delays |
✓ |
|
TIMESIGNATURES |
timesignatures |
✓ |
|
TICKCOUNTS |
tickcounts |
✓ |
|
COMBOS |
combos |
✓ |
|
WARPS |
warps |
✓ |
|
SPEEDS |
speeds |
✓ |
|
SCROLLS |
scrolls |
✓ |
|
FAKES |
fakes |
✓ |
|
LABELS |
labels |
✓ |
|
ATTACKS |
attacks |
✓ |
|
OFFSET |
offset |
✓ |
|
DISPLAYBPM |
displaybpm |
✓ |
- 1(1,2,3)
These keys are aliases supported by StepMania. The attribute will only use the alias if it’s present in the backing dictionary and the standard name is not.
Known properties supported by both the SM and SSC formats are documented in
BaseSimfile
and BaseChart
. These are exactly
the known properties for SMSimfile
and SMChart
. The SSC
format then adds additional known properties on top of the base set.
Here is all of the relevant documentation:
-
class
simfile.base.
BaseSimfile
(*, file: Optional[Union[TextIO, Iterator[str]]] = None, string: Optional[str] = None, strict: bool = True) A simfile, including its metadata (e.g. song title) and charts.
Metadata is stored directly on the simfile object through a dict-like interface. Keys are unique (if there are duplicates, the last value wins) and converted to uppercase.
Additionally, properties recognized by the current stable version of StepMania are exposed through lower-case properties on the object for easy (and implicitly spell-checked) access. The following known properties are defined:
Metadata: title, subtitle, artist, titletranslit, subtitletranslit, artisttranslit, genre, credit, samplestart, samplelength, selectable, instrumenttrack, timesignatures
File paths: banner, background, lyricspath, cdtitle, music
Gameplay events: bgchanges, fgchanges, keysounds, attacks, tickcounts
Timing data: offset, bpms, stops, delays
If a desired simfile property isn’t in this list, it can still be accessed as a dict item.
By default, the underlying parser will throw an exception if it finds any stray text between parameters. This behavior can be overridden by setting strict to False in the constructor.
-
class
simfile.base.
BaseChart
One chart from a simfile.
All charts have the following known properties: stepstype, description, difficulty, meter, radarvalues, and notes.
-
class
simfile.ssc.
SSCSimfile
(*, file: Optional[Union[TextIO, Iterator[str]]] = None, string: Optional[str] = None, strict: bool = True) SSC implementation of
BaseSimfile
.Adds the following known properties:
SSC version: version
Metadata: origin, labels, musiclength, lastsecondhint
File paths: previewvid, jacket, cdimage, discimage, preview
Gameplay events: combos, speeds, scrolls, fakes
Timing data: warps
-
class
simfile.ssc.
SSCChart
SSC implementation of
BaseChart
.Unlike
SMChart
, SSC chart metadata is stored as key-value pairs, so this class allows full modification of its backing OrderedDict.Adds the following known properties:
Metadata: chartname, chartstyle, credit, timesignatures
File paths: music
Gameplay events: tickcounts, combos, speeds, scrolls, fakes, attacks
Timing data: bpms, stops, delays, warps, labels, offset, displaybpm