assp

assp is a standalone NASM x86-64 port of rssp, the Rust StepMania simfile parser.

The executable is built from assembly. The Rust crate in this directory is only an optional test and baseline harness around the assembly executable and ABI. build.ps1 does not compile or link Rust code unless one of the RSSP comparison modes is requested.

Layout

• asm/app/main.asm: standalone app flow, argument parsing, reports.
• asm/app/linux64.asm, asm/app/freebsd64.asm, asm/app/win64.asm: native OS entrypoints and file/clock/stdout primitives.
• asm/core/: parser, scanner, hashing, timing, density, pattern, and chart analysis routines.
• include/assp.inc: NASM ABI constants, layouts, and shared macros.
• include/win64.inc: Win32 constants for the standalone executable.
• include/assp.h: C ABI declarations for external callers.
• src/: Rust FFI wrappers used by tests.
• tests/: Rust parity and smoke tests for the assembly ABI.
• fixtures/: small checked-in simfiles used by tests and parity scripts.

For the full exported ABI, read include/assp.h. For Rust-side call shape and test coverage, read src/abi.rs and tests/.

Requirements

• Windows x64
• nasm on PATH
• A Windows x64 linker: Visual Studio Build Tools, lld-link, or Rust's rust-lld
• Windows SDK x64 import libraries
• cargo only for Rust tests and parity harnesses

Linux and FreeBSD native builds use:

• nasm
• ld, cc, or gcc

Build

From this directory:

.\build.ps1

From the workspace root:

.\assp\build.ps1

The Windows executable is written to assp\target\assp.exe.

From Linux or FreeBSD, build the native ELF64 executable:

sh build.sh

The target OS is auto-detected from uname. The executable is written to assp/target/assp.

Useful native Unix build modes:

sh build.sh --clean
sh build.sh --target linux
sh build.sh --target freebsd
sh build.sh --profile-symbols
sh build.sh --phase-profile
sh build.sh --startup-trace
sh build.sh --run-fixture

--target freebsd selects the native FreeBSD syscall platform file. Build and run it on FreeBSD for an executable that can actually execute those syscalls. --startup-trace emits low-level FreeBSD startup breadcrumbs on stderr.

Useful build modes:

.\build.ps1 -Clean
.\build.ps1 -ProfileSymbols
.\build.ps1 -PhaseProfile

Run

Run the default Camellia fixture through the build script:

.\build.ps1 -RunFixture

Analyze every chart in a simfile, matching RSSP's default file behavior:

.\target\assp.exe .\fixtures\camellia_mix.ssc

List charts in a simfile:

.\target\assp.exe .\fixtures\camellia_mix.ssc list

Run one chart:

.\target\assp.exe .\fixtures\camellia_mix.ssc 4

The explicit all-chart mode remains available:

.\target\assp.exe .\fixtures\camellia_mix.ssc all

RSSP All-Parity Harness

The full golden parity data and all_parity test live in the rssp tree, but you can launch that harness from this directory and point it at the built ASSP executable:

.\all-parity.ps1 -Quiet

By default the script expects assp and rssp to be sibling directories. If they are not, pass the RSSP repository root:

.\all-parity.ps1 -RsspPath C:\path\to\rssp -Quiet

Use -Filter and -Exact for one file:

.\all-parity.ps1 -NoBuild -Exact -Filter "Hard-Boiled Eggs 2\Reallywanna\reallywanna.ssc.zst"

Extra all_parity harness arguments can still be passed after -- when needed.

ASSP Baseline Harness

fast-parity.ps1 runs only ASSP. It walks a pack tree, runs assp.exe --json for each .sm, .ssc, .sm.zst, and .ssc.zst file, and compares the output to compressed baselines in a directory you choose. By default it uses the checked-in tests\data\packs tree and the same mixed baseline sources as RSSP's full all_parity test:

• <md5>.json.zst for ITGmania/reference harness fields such as metadata, BPMs, hashes, timing, NPS, step counts, tech counts, and stream breakdowns.
• <md5>.rssp.json.zst for RSSP-owned fields such as matrix rating, SN breakdowns, sn_breaks, mono/candle stats, boxes, and anchors.

Compare against the existing RSSP JSON baselines:

.\fast-parity.ps1 -NoBuild -Quiet

Create or refresh ASSP-owned snapshot baselines in the same sharded layout:

.\fast-parity.ps1 -Update -Quiet

To compare against one complete JSON snapshot instead of the mixed full-parity sources, use JSON mode. Auto lookup prefers <md5>.assp.json.zst when present, then falls back to <md5>.rssp.json.zst, then <md5>.json.zst.

.\fast-parity.ps1 -NoBuild -CompareMode json -BaselineSuffix assp -Quiet

Quiet runs use parallel ASSP processes by default, capped at eight workers. Use -Jobs to tune that. Failure output is capped at 50 files by default; use -MaxFailures 0 to collect every failure.

Use filters for focused runs:

.\fast-parity.ps1 -NoBuild -Exact -Filter "138 Is Great\baam-138\steps.ssc.zst"

Quiet all-chart modes:

.\target\assp.exe .\fixtures\camellia_mix.ssc quiet
.\target\assp.exe .\fixtures\camellia_mix.ssc bench

quiet and bench process every chart without printing chart reports. bench is intended for timing the parser/report computation without console output.

Emit RSSP-shaped JSON for every chart:

.\target\assp.exe .\fixtures\camellia_mix.ssc --json

RSSP Parity

The comparison modes build assp.exe, run the local RSSP Rust CLI, and compare report fields.

Compare one chart:

.\build.ps1 -CompareRssp -Fixture .\fixtures\camellia_mix.ssc -Chart 4

Compare every chart in one fixture:

.\build.ps1 -CompareAllCharts -Fixture .\fixtures\camellia_mix.ssc

Compare every bundled fixture:

.\build.ps1 -CompareFixtures

Compare a song pack recursively:

.\build.ps1 -Pack "..\songs\MyPack" -Report .\target\my_pack_parity.log -KeepGoing

-Pack implies -CompareAllCharts. -KeepGoing keeps collecting mismatches after a file fails. -Report writes the same pass/fail lines and mismatch list to a log file.

Benchmark And Profile

Process-level ASSP vs RSSP benchmark:

.\bench.ps1 -Fixture .\fixtures\camellia_mix.ssc -AllCharts -Runs 5 -Warmup 1 -Report .\target\bench_camellia.csv

Benchmark a whole pack:

.\bench.ps1 -Pack ".\fixtures\ITL Online 2026" -Runs 5 -Warmup 1 -Report .\target\bench_itl.csv

Use -AsspNoReport on all-chart benchmarks to run assp.exe <file> bench and exclude text report formatting and output.

Capture an ETW CPU-sampling trace with symbols:

.\profile.ps1 -Fixture .\fixtures\camellia_mix.ssc -Chart all -Output .\target\assp_cpu_camellia.etl

profile.ps1 uses xperf and must run from an elevated PowerShell prompt.

Run the built-in phase timers without admin rights:

.\phase-profile.ps1 -Fixture .\fixtures\camellia_mix.ssc -Runs 3

This builds with -PhaseProfile and reports average ticks, milliseconds, and stage percentages for the major parser/report stages.

Rust Harness

Run optional Rust tests:

cargo test

The Cargo harness assembles asm/core/ routines for ABI parity tests. It is not part of the standalone executable build path.

Porting Priorities

1. Keep byte scanning, chart extraction, and metadata parsing deterministic.
2. Preserve RSSP-compatible note minimization, hashing, timing, and report fields.
3. Prefer caller-owned buffers and fixed layouts at the assembly ABI boundary.
4. Extend full step-parity coverage before expanding standalone reporting.