iModpack 1.0.0

iModpack - All-in-One Minecraft Modpack Library

A comprehensive C# library for packing and unpacking Minecraft modpacks, supporting both standard .zip format and Modrinth .mrpack format.

Installation

Install the package via NuGet: dotnet add package iModpack Or via Package Manager:Install-Package iModpack

Features

• Pack modpacks into standard ZIP or Modrinth .mrpack format
• Unpack modpacks from both formats
• Convert between ZIP and .mrpack formats
• Validate modpack files
• Display information about modpack contents
• Security validation for Modrinth paths
• Hash calculation (SHA1 and SHA512) for file verification
• Automatic download script generation for Modrinth mods
• Progress reporting through events
• Comprehensive error handling with detailed results

Supported Formats

Modrinth (.mrpack)

Fully compliant with the Modrinth Modpack Format specification:

• Format version 1
• Support for overrides, server-overrides, and client-overrides
• Complete metadata handling
• File download information
• Environment specifications (client/server)
• Dependencies management

Standard ZIP

Traditional ZIP-based modpacks with optional metadata:

• Custom modpack.json metadata
• Directory structure preservation
• Cross-platform compatibility

Usage

Basic Example

using iModpack;

// Create an instance
var modpack = new iModpack.iModpack();

// Subscribe to progress events (optional)
modpack.ProgressReported += message => Console.WriteLine($"Progress: {message}");
modpack.ErrorReported += error => Console.WriteLine($"Error: {error}");

// Pack a Modrinth modpack
var metadata = new ModrinthModpack
{
    Name = "My Awesome Modpack",
    Summary = "A great modpack for survival gameplay",
    Dependencies = new Dictionary<string, string>
    {
        ["minecraft"] = "1.20.1",
        ["fabric-loader"] = "0.14.24"
    }
};

var result = await modpack.PackModrinthAsync("./my_modpack_source", "my_modpack.mrpack", metadata);
if (result.Success)
{
    Console.WriteLine(result.Message);
}
else
{
    Console.WriteLine($"Failed: {result.Message}");
}

Advanced Examples

Pack a Standard ZIP Modpack

var modpack = new iModpack.iModpack();

var metadata = new StandardModpack
{
    Name = "My Standard Pack",
    Version = "1.0.0",
    MinecraftVersion = "1.20.1",
    ModLoader = "forge",
    ModLoaderVersion = "47.2.0"
};

var result = await modpack.PackStandardAsync("./source_directory", "modpack.zip", metadata);

Unpack a Modpack

var modpack = new iModpack.iModpack();

// Works with both .mrpack and .zip files
var result = await modpack.UnpackModrinthAsync("modpack.mrpack", "./extracted");
// or
var result = await modpack.UnpackStandardAsync("modpack.zip", "./extracted");

if (result.Success && result.Data is ModrinthModpack metadata)
{
    Console.WriteLine($"Unpacked: {metadata.Name}");
    Console.WriteLine($"Files: {metadata.Files.Count}");
}

Convert Between Formats

var modpack = new iModpack.iModpack();

// Convert ZIP to Modrinth
var result = await modpack.ConvertModpackAsync("standard.zip", "converted.mrpack", toModrinth: true);

// Convert Modrinth to ZIP
var result2 = await modpack.ConvertModpackAsync("modpack.mrpack", "converted.zip", toModrinth: false);

Validate a Modpack

var modpack = new iModpack.iModpack();

var result = await modpack.ValidateModpackAsync("modpack.mrpack");
if (result.Success)
{
    var validationData = result.Data as dynamic;
    Console.WriteLine($"Valid: {validationData.IsValid}");
}

Get Modpack Information

var modpack = new iModpack.iModpack();

var result = await modpack.GetModpackInfoAsync("modpack.mrpack");
if (result.Success && result.Data is ModrinthModpack info)
{
    Console.WriteLine($"Name: {info.Name}");
    Console.WriteLine($"Version: {info.VersionId}");
    Console.WriteLine($"Dependencies:");
    foreach (var dep in info.Dependencies)
    {
        Console.WriteLine($"  {dep.Key}: {dep.Value}");
    }
}

Utility Functions

Create Sample Modpack Structure

var result = await ModpackUtilities.CreateSampleModpackAsync("./sample_pack", "Test Pack");
if (result.Success)
{
    Console.WriteLine("Sample structure created!");
}

Analyze Directory and Auto-Generate Metadata

var result = await ModpackUtilities.AnalyzeDirectoryAsync("./my_pack", "My Pack");
if (result.Success)
{
    var analysis = result.Data as dynamic;
    var metadata = analysis.Metadata as ModrinthModpack;
    
    // Use the generated metadata to pack
    var modpack = new iModpack.iModpack();
    await modpack.PackModrinthAsync("./my_pack", "auto_generated.mrpack", metadata);
}

Compare Two Modpacks

var result = await ModpackUtilities.CompareModpacksAsync("pack1.mrpack", "pack2.mrpack");
if (result.Success)
{
    var comparison = result.Data as dynamic;
    Console.WriteLine($"Files added: {comparison.FileComparison.Summary.Added}");
    Console.WriteLine($"Files removed: {comparison.FileComparison.Summary.Removed}");
    Console.WriteLine($"Files modified: {comparison.FileComparison.Summary.Modified}");
}

Hash Calculation

// Static utility methods
string sha1 = await iModpack.iModpack.CalculateSHA1Async("myfile.jar");
string sha512 = await iModpack.iModpack.CalculateSHA512Async("myfile.jar");

// Validate Modrinth paths
bool isValid = iModpack.iModpack.ValidateModrinthPath("mods/my-mod.jar"); // true
bool isInvalid = iModpack.iModpack.ValidateModrinthPath("../../../dangerous"); // false

Directory Structure

For Modrinth Packs

Your source directory should follow this structure:

my_modpack/
├── overrides/           # Files for all installations
│   ├── config/
│   ├── mods/           # Optional: local mods not from downloads
│   └── options.txt
├── server-overrides/    # Server-only files (optional)
│   └── config/
└── client-overrides/    # Client-only files (optional)
    └── config/

For Standard ZIP Packs

Any directory structure is supported:

my_modpack/
├── mods/
├── config/
├── saves/
└── any_other_files/

Result Handling

All operations return a ModpackResult object:

public class ModpackResult
{
    public bool Success { get; set; }
    public string? Message { get; set; }
    public Exception? Exception { get; set; }
    public object? Data { get; set; }
}

Error Handling Example

var result = await modpack.PackModrinthAsync(sourceDir, outputPath, metadata);

if (!result.Success)
{
    Console.WriteLine($"Operation failed: {result.Message}");
    
    if (result.Exception != null)
    {
        Console.WriteLine($"Exception: {result.Exception}");
    }
}

Events

Subscribe to events for progress monitoring:

var modpack = new iModpack.iModpack();

modpack.ProgressReported += (message) => {
    Console.WriteLine($"[PROGRESS] {message}");
    // Update UI progress bar, etc.
};

modpack.ErrorReported += (error) => {
    Console.WriteLine($"[ERROR] {error}");
    // Log error, show notification, etc.
};

Dependencies

• .NET 8.0
• System.Text.Json (for JSON handling)
• System.Security.Cryptography.Algorithms (for hash calculation)
• Built-in System.IO.Compression (for ZIP operations)

NuGet Package

This library is available as a NuGet package. After installation, simply add: using iModpack;

API Reference

Main Classes

• iModpack - Main class for modpack operations
• ModrinthModpack - Modrinth format metadata model
• StandardModpack - Standard ZIP format metadata model
• ModpackResult - Operation result wrapper
• ModpackUtilities - Static utility methods

Main Methods

• PackModrinthAsync() - Pack directory to .mrpack
• PackStandardAsync() - Pack directory to .zip
• UnpackModrinthAsync() - Unpack .mrpack file
• UnpackStandardAsync() - Unpack .zip file
• ConvertModpackAsync() - Convert between formats
• ValidateModpackAsync() - Validate modpack file
• GetModpackInfoAsync() - Get modpack information

License

This project is open source. Please check the license file for details.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Modrinth Specification Compliance

This library fully implements the Modrinth Modpack Format specification, including:

• ✅ Format version handling
• ✅ Game specification
• ✅ File downloads with hash verification
• ✅ Environment specifications (client/server)
• ✅ Dependencies management
• ✅ Override folder support (overrides, server-overrides, client-overrides)
• ✅ Path security validation
• ✅ MIME type compliance (application/x-modrinth-modpack+zip)

Security Features

• Path Traversal Protection: Validates all file paths to prevent directory traversal attacks
• Hash Verification: Supports SHA1 and SHA512 hash calculation and verification
• URL Validation: Ensures download URLs are properly formatted
• File Size Validation: Tracks and validates file sizes
• Exception Handling: Comprehensive error handling with detailed exception information