Skip to content

MIGRATION_2.0.md

Latest commit

 

History

History
167 lines (118 loc) · 5.59 KB

MIGRATION_2.0.md

File metadata and controls

167 lines (118 loc) · 5.59 KB
Raw

Migration Guide: ReFrontier 1.x to 2.0

This guide covers breaking changes when upgrading from ReFrontier 1.x to 2.0.

Summary of Breaking Changes

  1. Architecture: Static methods replaced with dependency injection
  2. CLI: Custom argument parser replaced with System.CommandLine
  3. Auto-preprocessing: FrontierTextTool and FrontierDataTool now auto-detect encrypted/compressed files
  4. File output behavior: Removed --noFileRewrite option - files are no longer overwritten in place
  5. CLI option renamed: --log renamed to --saveMeta for clarity
  6. CLI option removed: --close removed - program now always exits immediately

Architecture Changes

Before (1.x): Static Methods with Lazy Singletons

// Old static API
Crypto.DecryptEcd(buffer, key);
Pack.JPKEncode(inputPath, compressionType, level);
Unpack.JPKDecode(inputPath);

After (2.0): Instance Methods with Dependency Injection

// New instance-based API with default dependencies
var service = new FileProcessingService();
service.EncryptEcdFile(inputFile, metaFile, cleanUp);

var packingService = new PackingService();
packingService.JPKEncode(inputPath, outputPath, compressionType, level);

var unpackingService = new UnpackingService();
unpackingService.JPKDecode(inputPath, outputPath);

Using Dependency Injection (for testing or custom implementations)

// Create with custom dependencies
IFileSystem fileSystem = new RealFileSystem();
ILogger logger = new ConsoleLogger();
var config = FileProcessingConfig.Default();

var service = new FileProcessingService(fileSystem, logger, config);

Available Abstractions

Interface Default Implementation Purpose
IFileSystem RealFileSystem File I/O operations
ILogger ConsoleLogger Console output
ICodecFactory CodecFactory JPK codec creation

CLI Argument Changes

The CLI now uses System.CommandLine for argument parsing.

ReFrontier CLI

# 1.x syntax
./ReFrontier mhfdat.bin --log

# 2.0 syntax (--log renamed to --saveMeta)
./ReFrontier mhfdat.bin --saveMeta

Most CLI arguments remain compatible. Key options:

Option Description
--saveMeta Save metadata files for repacking/re-encryption (was --log)
--nonRecursive Disable recursive unpacking (recursive is the default)
--compress=<type>,<level> Compress with specified type (0-4) and level
--encrypt Encrypt output file
--pack Repack directory
--cleanUp Delete intermediate files

FrontierTextTool CLI

# Extract text to CSV (outputs to mhfdat.csv)
./FrontierTextTool mhfdat.bin --fulldump --trueOffsets --nullStrings

# Insert text from CSV (outputs to output/mhfdat.bin)
./FrontierTextTool mhfdat.bin --insert --csv mhfdat.csv

FrontierDataTool CLI

# Extract data structures
./FrontierDataTool --dump --suffix demo --mhfpac mhfpac.bin --mhfdat mhfdat.bin --mhfinf mhfinf.bin

# Import data from CSV (outputs to output/)
./FrontierDataTool --import --csv Melee.csv --mhfdat mhfdat.bin

Auto-Preprocessing

FrontierTextTool and FrontierDataTool now automatically handle encrypted (ECD/EXF) and compressed (JPK) files. You no longer need to manually decrypt/decompress before processing.

# 1.x workflow (manual preprocessing required)
./ReFrontier mhfdat.bin --log           # Decrypt/decompress first
./FrontierTextTool output/mhfdat.bin.decd --fulldump --trueOffsets --nullStrings

# 2.0 workflow (automatic preprocessing)
./FrontierTextTool mhfdat.bin --fulldump --trueOffsets --nullStrings

CLI Option Changes

Renamed: --log → --saveMeta

The --log option has been renamed to --saveMeta to better describe its purpose: saving metadata files (.meta and .log) required for repacking and re-encryption.

# Before (1.x)
./ReFrontier mhfdat.bin --log

# After (2.0)
./ReFrontier mhfdat.bin --saveMeta

Removed: --close

The --close option has been removed. The program now always exits immediately after completion. This was legacy behavior for Windows GUI usage that is no longer needed for a CLI tool.

Service Layer

New service classes provide better separation of concerns:

Service Responsibility
FileProcessingService Encryption/decryption operations
PackingService JPK encoding and archive packing
UnpackingService JPK decoding and archive unpacking
FilePreprocessor Auto-detect and preprocess files

File Output Behavior

In 1.x, decryption and decompression would overwrite the original file by default. The --noFileRewrite option was added to disable this behavior.

In 2.0, the original file is never overwritten. Output always goes to a new file:

Operation Input Output
ECD Decryption file.bin file.bin.decd
EXF Decryption file.bin file.bin.dexf
JPK Decompression file.jkr file.jkr.bin (or similar)

This is safer and more predictable. If you relied on the old overwrite behavior, update your scripts to use the new output paths.

Migration Checklist

  • Update any code using static methods to use service instances
  • Review CLI scripts for argument compatibility
  • Remove manual decrypt/decompress steps for FrontierTextTool/FrontierDataTool
  • Update any custom integrations to use the new DI pattern
  • Update scripts that relied on --noFileRewrite or in-place file modification
  • Replace --log with --saveMeta in all scripts
  • Remove --close from scripts (no longer needed)