Unzip Single File with Rename (async)

Overview

The Unzip Single File with Rename (async) function extracts a specific file from a zip archive and renames it during extraction. This is perfect for scenarios where you need to extract only one particular file from an archive and give it a new name.

Function Description

Node Name: Unzip Single File with Rename (async)
Category: Archive Manager
Type: Asynchronous (non-blocking operation)

Extracts a specifically named file from a ZIP archive, renames it to your specified filename, and runs the operation in a background thread with real-time progress tracking and completion callbacks.

Blueprint Usage

Input Parameters

Parameter	Type	Description
Path to Zip	String	Full absolute path to the ZIP file you want to extract from
Source Filename	String	Exact name of the file to extract from the archive (e.g., “config.json”, “subfolder/data.txt”)
Delete After Extraction	Boolean	If true, deletes the ZIP file after successful extraction
Extracted Data Filename	String	New filename for the extracted file (e.g., “new_asset_file_name.psd”)
Get Progress	Zip Progress Delegate	Callback function that receives progress updates (0.0 to 1.0)
Callback	Unzip Task Complete Delegate	Callback function executed when extraction completes

Output Parameters

Parameter	Type	Description
Return Value	Zip Task	Reference to the background task (can be used for cancellation)

Delegate Parameters

CustomEvent 1 (Progress Event)

Progress (Float): Extraction progress from 0.0 (0%) to 1.0 (100%)

CustomEvent 2 (Completion Event)

Success (Boolean): true if extraction succeeded, false if failed
Path to Files (Array of Strings): Array containing the path to the extracted and renamed file

Blueprint Setup Steps

1. Create Custom Events for Callbacks

CustomEvent 1: Right-click → Add Custom Event → Name: “CustomEvent 1”
- Add input parameter: Progress (Float)
CustomEvent 2: Right-click → Add Custom Event → Name: “CustomEvent 2”
- Add input parameter: Success (Boolean)
- Add input parameter: Path to Files (Array of Strings)

2. Add the Unzip Single File with Rename (async) Node

Search for “Unzip Single File with Rename (async)”
Set Path to Zip: “F:/TestData/ArchiveManager/ObjectsArchive.zip”
Set Source Filename: “asset_file_200mb.pub”
Set Delete After Extraction: ☐ (keep original ZIP file)
Set Extracted Data Filename: “new_asset_file_name.pub”

3. Connect Progress Tracking

Connect CustomEvent 1 to Get Progress delegate
Add Format Text node to display progress:
- Format: “Unzipping: {Progress}%”
- Connect Progress × 100 to format parameter

4. Connect Completion Callback

Connect CustomEvent 2 to Callback delegate
Add For Each Loop to process the extracted file:
- Connect Path to Files array to For Each Loop input
- Display the extracted file path using Print String

5. Add Final Completion Message

After the For Each Loop, add Print String: “Unzipping complete”

C++ Usage

Basic Implementation

Click to see the code

class YOURGAME_API UBasicUnzipExample : public UObject
{
    GENERATED_BODY()

public:
    UFUNCTION(BlueprintCallable)
    bool StartUnzipWithRename(const FString& ZipPath, const FString& SourceFile, const FString& NewName);

private:
    UFUNCTION()
    void OnExtractionProgress(float Progress);
    
    UFUNCTION()
    void OnExtractionComplete(bool bSuccess, TArray<FString> ExtractedFiles);
    
    UPROPERTY()
    UZipTask* CurrentTask;
};

bool UBasicUnzipExample::StartUnzipWithRename(const FString& ZipPath, const FString& SourceFile, const FString& NewName)
{
    // Input validation
    if (ZipPath.IsEmpty() || SourceFile.IsEmpty() || NewName.IsEmpty())
    {
        UE_LOG(LogTemp, Error, TEXT("Invalid parameters: all strings must be non-empty"));
        return false;
    }

    // Check if file exists
    if (!FPaths::FileExists(ZipPath))
    {
        UE_LOG(LogTemp, Error, TEXT("Zip file not found: %s"), *ZipPath);
        return false;
    }

    // Setup delegates
    FZipProgressDelegate ProgressDelegate;
    ProgressDelegate.BindUFunction(this, FName("OnExtractionProgress"));

    FUnzipTaskCompleteDelegate CompleteDelegate;
    CompleteDelegate.BindUFunction(this, FName("OnExtractionComplete"));

    // Start extraction with task validation
    CurrentTask = UArchiveManagerBPLibrary::UnzipAsyncWithRename(
        ZipPath,              // Path to zip
        SourceFile,           // Source filename
        false,                // Delete after extraction
        NewName,              // New filename
        ProgressDelegate,     // Progress callback
        CompleteDelegate      // Completion callback
    );

    if (CurrentTask)
    {
        UE_LOG(LogTemp, Log, TEXT("Unzip task started: %s -> %s"), *SourceFile, *NewName);
        return true;
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to create unzip task"));
        return false;
    }
}

void UBasicUnzipExample::OnExtractionProgress(float Progress)
{
    UE_LOG(LogTemp, VeryVerbose, TEXT("Extraction progress: %.1f%%"), Progress * 100.0f);
}

void UBasicUnzipExample::OnExtractionComplete(bool bSuccess, TArray<FString> ExtractedFiles)
{
    CurrentTask = nullptr; // Clear task reference

    if (bSuccess)
    {
        UE_LOG(LogTemp, Log, TEXT("Extraction completed successfully"));
        for (const FString& File : ExtractedFiles)
        {
            UE_LOG(LogTemp, Log, TEXT("Extracted file: %s"), *File);
        }
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Extraction failed"));
    }
}

Advanced Asset Import System

Click to see the code

UCLASS()
class YOURGAME_API UAssetImportManager : public UObject
{
    GENERATED_BODY()

public:
    UFUNCTION(BlueprintCallable)
    bool ImportSpecificAsset(const FString& ArchivePath, const FString& AssetName, const FString& ImportName);

    UFUNCTION(BlueprintCallable)
    void CancelCurrentImport();

private:
    UFUNCTION()
    void OnImportProgress(float Progress);
    
    UFUNCTION()
    void OnImportComplete(bool bSuccess, TArray<FString> ExtractedFiles); // Fixed: Added <FString>
    
    UPROPERTY()
    FString CurrentImportName;
    
    UPROPERTY()
    UZipTask* CurrentTask; // Added: Track current task
};

bool UAssetImportManager::ImportSpecificAsset(const FString& ArchivePath, const FString& AssetName, const FString& ImportName)
{
    // Validate inputs
    if (ArchivePath.IsEmpty() || AssetName.IsEmpty() || ImportName.IsEmpty())
    {
        UE_LOG(LogTemp, Error, TEXT("Invalid parameters for asset import"));
        return false;
    }

    // Check if already importing
    if (CurrentTask)
    {
        UE_LOG(LogTemp, Warning, TEXT("Import already in progress, cancelling previous task"));
        CancelCurrentImport();
    }

    // Validate archive exists
    if (!FPaths::FileExists(ArchivePath))
    {
        UE_LOG(LogTemp, Error, TEXT("Archive not found: %s"), *ArchivePath);
        return false;
    }

    CurrentImportName = ImportName;
    
    FZipProgressDelegate ProgressDelegate;
    ProgressDelegate.BindUFunction(this, FName("OnImportProgress"));
    
    FUnzipTaskCompleteDelegate CompleteDelegate;
    CompleteDelegate.BindUFunction(this, FName("OnImportComplete"));
    
    CurrentTask = UArchiveManagerBPLibrary::UnzipAsyncWithRename(
        ArchivePath,
        AssetName,
        false,
        ImportName,
        ProgressDelegate,
        CompleteDelegate
    );

    if (CurrentTask)
    {
        UE_LOG(LogTemp, Log, TEXT("Started importing asset '%s' as '%s'"), *AssetName, *ImportName);
        return true;
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to start asset import task"));
        CurrentImportName.Empty();
        return false;
    }
}

void UAssetImportManager::CancelCurrentImport()
{
    if (CurrentTask)
    {
        UArchiveManagerBPLibrary::Cancel(); // Cancel current operation
        CurrentTask = nullptr;
        CurrentImportName.Empty();
        UE_LOG(LogTemp, Log, TEXT("Import operation cancelled"));
    }
}

void UAssetImportManager::OnImportProgress(float Progress)
{
    UE_LOG(LogTemp, VeryVerbose, TEXT("Import progress for '%s': %.1f%%"), *CurrentImportName, Progress * 100.0f);
}

void UAssetImportManager::OnImportComplete(bool bSuccess, TArray<FString> ExtractedFiles)
{
    CurrentTask = nullptr; // Clear task reference

    if (bSuccess)
    {
        UE_LOG(LogTemp, Log, TEXT("Successfully imported asset as '%s'"), *CurrentImportName);
        
        for (const FString& File : ExtractedFiles)
        {
            UE_LOG(LogTemp, Log, TEXT("Extracted file: %s"), *File);
            
            // Additional processing could be done here:
            // - Load the asset into Unreal Engine
            // - Validate file integrity
            // - Update asset registry
        }
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to import asset '%s'"), *CurrentImportName);
    }

    CurrentImportName.Empty();
}

Save Game Recovery System

Click to see the code

UCLASS()
class YOURGAME_API UGameSaveManager : public UObject
{
    GENERATED_BODY()

public:
    UFUNCTION(BlueprintCallable)
    bool RecoverSpecificSave(const FString& BackupArchive, const FString& SaveFileName);

private:
    UFUNCTION()
    void OnRecoveryProgress(float Progress);
    
    UFUNCTION()
    void OnRecoveryComplete(bool bSuccess, TArray<FString> ExtractedFiles);
    
    UPROPERTY()
    UZipTask* RecoveryTask;
    
    UPROPERTY()
    FString RecoveryTargetName;
};

bool UGameSaveManager::RecoverSpecificSave(const FString& BackupArchive, const FString& SaveFileName)
{
    // Validate inputs
    if (BackupArchive.IsEmpty() || SaveFileName.IsEmpty())
    {
        UE_LOG(LogTemp, Error, TEXT("Invalid parameters for save recovery"));
        return false;
    }

    // Check if archive exists
    if (!FPaths::FileExists(BackupArchive))
    {
        UE_LOG(LogTemp, Error, TEXT("Backup archive not found: %s"), *BackupArchive);
        return false;
    }

    // Cancel any existing recovery
    if (RecoveryTask)
    {
        UE_LOG(LogTemp, Warning, TEXT("Previous recovery in progress, cancelling"));
        UArchiveManagerBPLibrary::Cancel();
        RecoveryTask = nullptr;
    }

    // Generate unique recovery filename
    FString Timestamp = FDateTime::Now().ToString(TEXT("%Y%m%d_%H%M%S"));
    RecoveryTargetName = FString::Printf(TEXT("recovered_%s_%s.sav"), 
        *SaveFileName, 
        *Timestamp);
    
    FZipProgressDelegate ProgressDelegate;
    ProgressDelegate.BindUFunction(this, FName("OnRecoveryProgress"));
    
    FUnzipTaskCompleteDelegate CompleteDelegate;
    CompleteDelegate.BindUFunction(this, FName("OnRecoveryComplete"));
    
    RecoveryTask = UArchiveManagerBPLibrary::UnzipAsyncWithRename(
        BackupArchive,
        SaveFileName,
        false,
        RecoveryTargetName,
        ProgressDelegate,
        CompleteDelegate
    );

    if (RecoveryTask)
    {
        UE_LOG(LogTemp, Log, TEXT("Started save recovery: %s -> %s"), *SaveFileName, *RecoveryTargetName);
        return true;
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to start save recovery task"));
        RecoveryTargetName.Empty();
        return false;
    }
}

void UGameSaveManager::OnRecoveryProgress(float Progress)
{
    UE_LOG(LogTemp, Log, TEXT("Save recovery progress: %.1f%%"), Progress * 100.0f);
}

void UGameSaveManager::OnRecoveryComplete(bool bSuccess, TArray<FString> ExtractedFiles)
{
    RecoveryTask = nullptr; // Clear task reference

    if (bSuccess && ExtractedFiles.Num() > 0)
    {
        UE_LOG(LogTemp, Log, TEXT("Save recovery successful: %s"), *ExtractedFiles[0]);
        
        // Additional recovery validation could be done here:
        // - Verify save file integrity
        // - Load and validate save data
        // - Backup original save before replacing
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Save recovery failed for: %s"), *RecoveryTargetName);
    }

    RecoveryTargetName.Empty();
}

Async Utility Function with Callback Handling

Click to see the code

namespace UFileExtractionUtils
{
    // Fixed version with proper async handling
    void ExtractSpecificFileWithTimestamp(
        const FString& ZipPath, 
        const FString& SourceFile, 
        const FString& FilePrefix,
        TFunction<void(bool, const FString&)> OnComplete) // Added callback parameter
    {
        // Input validation
        if (ZipPath.IsEmpty() || SourceFile.IsEmpty() || FilePrefix.IsEmpty())
        {
            UE_LOG(LogTemp, Error, TEXT("Invalid parameters for file extraction"));
            if (OnComplete) OnComplete(false, FString());
            return;
        }

        // Validate zip file exists
        if (!FPaths::FileExists(ZipPath))
        {
            UE_LOG(LogTemp, Error, TEXT("Zip file not found: %s"), *ZipPath);
            if (OnComplete) OnComplete(false, FString());
            return;
        }

        // Generate timestamp filename
        FString Timestamp = FDateTime::Now().ToString(TEXT("%Y%m%d_%H%M%S"));
        FString NewFileName = FString::Printf(TEXT("%s_%s.dat"), *FilePrefix, *Timestamp);
        
        // Setup delegates with proper binding
        FZipProgressDelegate ProgressDelegate;
        ProgressDelegate.BindLambda([NewFileName](float Progress)
        {
            UE_LOG(LogTemp, VeryVerbose, TEXT("Extracting %s: %.1f%%"), *NewFileName, Progress * 100.0f);
        });
        
        FUnzipTaskCompleteDelegate CompleteDelegate;
        CompleteDelegate.BindLambda([OnComplete, NewFileName](bool bSuccess, TArray<FString> ExtractedFiles)
        {
            if (bSuccess && ExtractedFiles.Num() > 0)
            {
                UE_LOG(LogTemp, Log, TEXT("Successfully extracted as: %s"), *ExtractedFiles[0]);
                if (OnComplete) OnComplete(true, ExtractedFiles[0]);
            }
            else
            {
                UE_LOG(LogTemp, Error, TEXT("Failed to extract file as: %s"), *NewFileName);
                if (OnComplete) OnComplete(false, FString());
            }
        });
        
        // Start extraction with task validation
        UZipTask* Task = UArchiveManagerBPLibrary::UnzipAsyncWithRename(
            ZipPath,
            SourceFile,
            false,
            NewFileName,
            ProgressDelegate,
            CompleteDelegate
        );

        if (!Task)
        {
            UE_LOG(LogTemp, Error, TEXT("Failed to create extraction task"));
            if (OnComplete) OnComplete(false, FString());
        }
        else
        {
            UE_LOG(LogTemp, Log, TEXT("Started extraction: %s -> %s"), *SourceFile, *NewFileName);
        }
    }

    // Usage example for the corrected utility function
    void ExampleUsage()
    {
        ExtractSpecificFileWithTimestamp(
            TEXT("C:/Archives/Data.zip"),
            TEXT("config.json"),
            TEXT("backup_config"),
            [](bool bSuccess, const FString& ExtractedPath)
            {
                if (bSuccess)
                {
                    UE_LOG(LogTemp, Log, TEXT("File successfully extracted to: %s"), *ExtractedPath);
                    // Process the extracted file here
                }
                else
                {
                    UE_LOG(LogTemp, Error, TEXT("Extraction failed"));
                }
            }
        );
    }
}

Advanced Features

Predictable File Selection

The Source Filename parameter allows you to:

Target specific files: Extract exactly the file you need by name
Navigate subdirectories: Use paths like “config/settings.json”
Handle case sensitivity: Match exact filenames as stored in archive

Automatic File Renaming

The Extracted Data Filename parameter allows you to:

Standardize naming: Convert random filenames to project conventions
Add timestamps: Create unique filenames for each extraction
Change extensions: Modify file format designation during extraction
Add prefixes/suffixes: Organize files with consistent naming patterns

Specific File Focus

This function is optimized for scenarios where you need a particular file:

Configuration loading: Extract specific config file from bundle
Asset importing: Extract particular asset file from package
Save game recovery: Extract specific save file from backup
Template extraction: Get specific template file from package

Progress Tracking for Targeted Files

Even for specific file extraction, progress tracking is valuable for:

Large file extraction (videos, high-res textures, models)
User feedback during import operations
Timeout detection for corrupted archives
Cancellation support for responsive UI

Common Use Cases

Game Development

Asset Pipeline: Import specific assets from artist packages
DLC Loading: Extract particular content file from DLC package
Save Recovery: Restore specific save file from backup
Texture Import: Extract particular high-resolution texture from package

Application Development

Document Import: Extract specific document from archive
Configuration Deploy: Extract particular config file with environment-specific naming
Template Installation: Extract specific template with project naming
Data Recovery: Restore particular data file from backup

Best Practices

Filename Strategy

Use exact names: Source filename must match exactly (case-sensitive)
Include paths: Use “subfolder/file.txt” for files in subdirectories
Descriptive output names: Include purpose, timestamp, or version in extracted filename
Follow conventions: Use project-specific naming standards
Avoid conflicts: Include unique identifiers to prevent overwrites

Error Handling

Validate source file: Ensure the specific file exists in archive
Check filename validity: Ensure extracted filename is valid for filesystem
Handle extraction failures: Provide meaningful error messages
Verify extracted file: Validate extracted file integrity

Performance Considerations

Ideal for specific assets: Perfect when you know exactly which file you need
Efficient extraction: Only processes the target file, ignores rest of archive
Memory efficient: Doesn’t load entire archive into memory
Quick operation: Faster than extracting all files when only one is needed

Extraction Behavior

File Selection: Extracts the specifically named file from the ZIP archive
Error on missing: Fails with clear error if source file not found
Renaming: File is renamed during extraction process, not after
Location: Extracted to same directory as source ZIP file
Original Preservation: Original filename is replaced with new name
Metadata: File timestamps and attributes are preserved

Common Errors

“Specified source file not found”

Cause: The filename doesn’t match any file in the archive
Solution: Check exact spelling and path of the file in the archive

“Failed opening zip archive”

Cause: Zip file doesn’t exist or is corrupted
Solution: Verify the zip file path and integrity

“Permission denied”

Cause: Insufficient permissions to write to extraction location
Solution: Check write permissions for the target directory

Unzip Single File with Rename (async)

Overview

Function Description

Blueprint Usage

Input Parameters

Output Parameters

Delegate Parameters

Blueprint Setup Steps

1. Create Custom Events for Callbacks

2. Add the Unzip Single File with Rename (async) Node

3. Connect Progress Tracking

4. Connect Completion Callback

5. Add Final Completion Message

C++ Usage

Basic Implementation

Advanced Asset Import System

Save Game Recovery System

Async Utility Function with Callback Handling

Advanced Features

Predictable File Selection

Automatic File Renaming

Specific File Focus

Progress Tracking for Targeted Files

Common Use Cases

Game Development

Application Development

Best Practices

Filename Strategy

Error Handling

Performance Considerations

Extraction Behavior

Common Errors

“Specified source file not found”

“Failed opening zip archive”

“Permission denied”

Unseen Roads

3D assets for virtual worlds

Lifelike AI Agents

Group VR for physical locations

Interactive domes