Archives

The Unity archive file format is a generic packaging format which can store any type of file, similar to a .zip file.

This file format is used by AssetBundles. The AssetBundle archive files are created as a final stage of the build process, e.g. BuildPipeline.BuildAssetBundles. They are mounted into the Unity virtual file system when the AssetBundle is loaded, e.g. AssetBundle.LoadFromFile.

This file format is also used for Player content when the Player is built with BuildOptions.CompressWithLz4. In that case the Archive is mounted automatically when the player runs.

This section describes lower-level APIs that Unity provides for working with archives.

Archive File System

The ArchiveFileInterface API can be use to load archives. They are mounted into a Unity.Content.ContentNamespace. Once Unity mounts the file, your application can access the files inside an Archive through any Unity systems that use Unity’s virtual file system. Use the AsyncReadManager to access the virtual file system directly.

Create and mount an archive

The following example describes how to create an archive with the ContentBuildInterface.ArchiveAndCompress function and mount the archive with the ArchiveFileInterface.MountAsync function. This example produces an archive that uses LZ4 compression and contains one text file.

using Unity.Collections.LowLevel.Unsafe;
using Unity.Content;
using Unity.IO.Archive;
using Unity.IO.LowLevel.Unsafe;
using UnityEngine;
#if UNITY_EDITOR
using UnityEditor.Build.Content;
#endif

public class SampleBehaviour : MonoBehaviour
{
#if UNITY_EDITOR
  unsafe void CreateAndMountArchive()
  { 
    // Create the Archive
    ResourceFile[] rFiles = new ResourceFile[1];
    ResourceFile rf = new ResourceFile();
    rf.fileName = "Assets/file1.txt"; // Path of the existing file, to copy into the Archive
    rf.fileAlias = "file1.txt";       // Path given to the file inside the Archive
    rFiles[0] = rf;

    string archivePath = System.IO.Path.Combine(Application.streamingAssetsPath, "myArchive");
    ContentBuildInterface.ArchiveAndCompress(rFiles, archivePath, UnityEngine.BuildCompression.LZ4);

    // Mount the Archive
    var ns = ContentNamespace.GetOrCreateNamespace("MyNamespace123");
    ArchiveHandle ahandle = ArchiveFileInterface.MountAsync(ns, archivePath, "a:");
    ahandle.JobHandle.Complete();

    string textFilePath = ahandle.GetMountPath() + "file1.txt"; // ns:/MyNamespace123/a:/file1.txt
    ReadCommand cmd;
    cmd.Size = 1024;
    cmd.Buffer = UnsafeUtility.Malloc(cmd.Size, 4, Unity.Collections.Allocator.Temp);
    cmd.Offset = 0;
    
    NativeArray<ReadCommand> cmds = new NativeArray<ReadCommand>(1, Allocator.Persistent);
    cmds[0] = cmd;

    ReadHandle rHandle = AsyncReadManager.Read(textFilePath, (ReadCommand*)cmds.GetUnsafePtr(), 1);
    rHandle.JobHandle.Complete();

    // ...At this point cmd.Buffer contains contents from file1.txt (up to 1024 bytes)...

    rHandle.Dispose();
    UnsafeUtility.Free(cmd.Buffer, Unity.Collections.Allocator.Temp);
    cmds.Dipose():

    ahandle.Unmount().Complete();
  }
#endif
}