stepmania-parser

A TypeScript + Peggy parser for StepMania 5 .ssc and .sm files with a normalized output schema.

Install

npm install stepmania-parser

Build

npm run build

Test

npm test

This runs the parser against the real .ssc and .sm fixtures in fixtures.

Test With A Real File

1. Put your real chart file inside fixtures, for example fixtures/song.ssc or fixtures/song.sm.
2. Run:

npm run parse:file -- fixtures/song.ssc

The command prints the parsed AST as JSON in two sections: HEADER and LEVELS.

You can also pass just the filename if it lives in fixtures, for example:

npm run parse:file -- sample.ssc

Usage

import { parseSSC } from 'stepmania-parser';

const ast = parseSSC(fileContent);
console.log(ast.header.title);
console.log(ast.levels.length);

Use parseSM from the same package root when you want to parse legacy .sm files explicitly.

Output Shape

The parser returns a normalized SSCFile structure:

• header: always-present metadata fields, with missing values filled with defaults
• levels: one entry per chart, including its metadata, notes, and any local gimmick changes

Supported Tags

The parser accepts the common # tags used by both .sm and .ssc files, including:

• Header metadata: TITLE, SUBTITLE, ARTIST, CREDIT, MUSIC, CDTITLE, BANNER, BACKGROUND, SAMPLESTART, SAMPLELENGTH, DISPLAYBPM, OFFSET
• Gimmick tags: BPMS, STOPS, DELAYS, WARPS, SCROLLS, TICKCOUNTS, COMBOS, FAKES, SPEEDS
• Chart tags: NOTEDATA, STEPSTYPE, DIFFICULTY, METER, DESCRIPTION, NOTES

SM is treated as the legacy format, but it uses the same supported tag set for shared header and gimmick data.

Missing tags are normalized instead of omitted, so consumers can rely on a stable object shape:

• missing text fields become ''
• missing numeric fields become 0
• missing array fields become []
• missing DISPLAYBPM becomes null