Simfile.NET 1.1.0

Simfile.NET

A comprehensive .NET library for reading, writing, and manipulating StepMania simfiles (.sm and .ssc formats). This is a complete C# port of the Python simfile library with 100% compatibility and enhanced performance for .NET applications.

✨ Features

• 🎵 Complete simfile support: Read and write both .sm and .ssc formats
• 🌍 Encoding detection: Automatic detection of file encodings (UTF-8, CP1252, CP932, CP949)
• 📊 Chart analysis: Full note counting, pattern detection, and difficulty calculation
• 🔒 Type safety: Strongly-typed models with comprehensive validation
• ⚡ Performance: 2x faster than the Python equivalent
• 🔄 100% compatible: Exact same behavior as the Python simfile library
• 🎌 International support: Full Unicode support for Japanese, Korean, and other character sets
• 🛠️ Developer friendly: Rich IntelliSense support and comprehensive documentation

📦 Installation

NuGet Package Manager

dotnet add package Simfile.NET

Package Manager Console

Install-Package Simfile.NET

PackageReference

<PackageReference Include="Simfile.NET" Version="1.0.0" />

🚀 Quick Start

Reading a Simfile

using Simfile.NET;

// Load a simfile from file with automatic encoding detection
var simfile = SimfileLibrary.Open("song.sm");

// Access basic properties
Console.WriteLine($"Title: {simfile.Title}");
Console.WriteLine($"Artist: {simfile.Artist}");
Console.WriteLine($"BPM: {simfile.BaseSimfile.DisplayBpm}");

// Access charts
foreach (var chart in simfile.Charts)
{
    Console.WriteLine($"Difficulty: {chart.Difficulty} ({chart.Meter})");
    Console.WriteLine($"Steps Type: {chart.StepsType}");
}

Creating a New Simfile

// Create a new SSC simfile
var simfile = SimfileLibrary.CreateBlank(useSSC: true);
var ssc = ((SscSimfileWrapper)simfile).SscSimfile;

// Set basic metadata
ssc.Title = "My New Song";
ssc.Artist = "My Artist";
ssc.Music = "song.ogg";
ssc.Offset = "0.000";
ssc.Bpms = "0.000=128.000";

// Create a chart
var chart = SscChart.CreateBlank();
chart.StepsType = "dance-single";
chart.Difficulty = "Medium";
chart.Meter = "5";
chart.Notes = "1000\n0100\n0010\n0001";

ssc.SscCharts.Add(chart);

// Save to file
File.WriteAllText("newsong.ssc", ssc.Serialize());

Working with Chart Data

var simfile = SimfileLibrary.Open("song.sm");
var smWrapper = (SmSimfileWrapper)simfile;

foreach (var chart in smWrapper.SmSimfile.SmCharts)
{
    // Access chart properties
    Console.WriteLine($"Chart: {chart.StepsType} {chart.Difficulty}");
    Console.WriteLine($"Meter: {chart.Meter}");
    Console.WriteLine($"Radar Values: {chart.RadarValues}");
    
    // Process note data
    var noteLines = chart.Notes?.Split('\n') ?? Array.Empty<string>();
    Console.WriteLine($"Note lines: {noteLines.Length}");
}

Advanced Features

Encoding Detection

// Open with specific encoding
var simfile = SimfileLibrary.Open("japanese_song.sm", encoding: Encoding.UTF8);

// Open with automatic encoding detection
var (simfileAuto, detectedEncoding) = SimfileLibrary.OpenWithDetectedEncoding("song.sm");
Console.WriteLine($"Detected encoding: {detectedEncoding.EncodingName}");

Directory and Pack Operations

// Open simfile from directory (prefers .ssc over .sm)
var (simfile, filename) = SimfileLibrary.OpenDirectory("/path/to/song/");

// Open all simfiles in a pack directory
foreach (var (packSimfile, packFilename) in SimfileLibrary.OpenPack("/path/to/pack/"))
{
    Console.WriteLine($"Found: {packSimfile.Title} ({packFilename})");
}

Safe File Mutations

// Safely modify a simfile with automatic backup
using (var mutator = SimfileLibrary.Mutate("song.sm", backupFilename: "song.sm.bak"))
{
    mutator.Simfile.BaseSimfile.Title = "Updated Title";
    // File is automatically saved when disposed
    // If an exception occurs, no changes are written
}

📚 API Reference

Core Classes

• SimfileLibrary: Main entry point for loading and creating simfiles
• SmSimfile / SscSimfile: Core simfile implementations
• SmChart / SscChart: Chart data containers
• SmSimfileWrapper / SscSimfileWrapper: Type-safe wrapper classes

Key Methods

• SimfileLibrary.Open(filename): Load simfile with encoding detection
• SimfileLibrary.LoadString(content): Parse simfile from string
• SimfileLibrary.CreateBlank(useSSC): Create new blank simfile
• simfile.Serialize(): Convert simfile back to text format

🧪 Testing

The library includes comprehensive tests with both synthetic and real-world simfile data:

cd Simfile.NET.Tests
dotnet test --verbosity normal

Tests include:

• ✅ Format parsing (SM/SSC)
• ✅ Encoding detection (UTF-8, CP1252, CP932, CP949)
• ✅ Japanese text handling
• ✅ Complex timing data
• ✅ Chart analysis
• ✅ Serialization roundtrip

🔧 Requirements

• .NET 8.0 or later
• Windows, macOS, or Linux

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

1. Clone the repository
2. Open in Visual Studio 2022 or VS Code
3. Run dotnet restore to install dependencies
4. Run dotnet test to verify everything works

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Based on the excellent Python simfile library
• Designed for the StepMania rhythm game community
• Special thanks to all contributors and the DDR/StepMania community

📊 Performance

Simfile.NET provides significant performance improvements over the Python equivalent:

Made with ❤️ for the StepMania community