File Providers

Introduction

File providers are essential components within CUE4Parse that facilitate convenient access to game directories, reading of archives and packages, and provide developers with a range of methods to efficiently manipulate and work with this data efficiently. CUE4Parse offers three built-in providers and two additional options for custom implementation.

---

Default _🪲

The default file provider is a pre-configured file provider designed for accessing archives within a local directory.

var provider = new DefaultFileProvider(
    directory: "D:\\Games\\PC\\XXXXXXX\\XXXXXXX\\Content\\Paks",
    searchOption: SearchOption.TopDirectoryOnly,
    isCaseInsensitive: true,
    versions: new VersionContainer(EGame.GAME_UE4_LATEST));

Additionally, you can specify multiple directories to include archives that may be remotely written in %localappdata% for example.

var provider = new DefaultFileProvider(
    directory: new DirectoryInfo("D:\\Games\\PC\\XXXXXXX\\XXXXXXX\\Content\\Paks"),
    extraDirectories: new DirectoryInfo[]
    {
        new(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData) + "\\XXXXXXX\\Saved\\Paks"),
        new(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData) + "\\XXXXXXX\\Saved\\DisabledPaks")
    },
    searchOption: SearchOption.TopDirectoryOnly,
    isCaseInsensitive: true,
    versions: new VersionContainer(EGame.GAME_UE4_LATEST));

APK _🪲

The APK file provider is another pre-configured file provider designed for parsing APK files and retrieving archives within them.

var provider = new ApkFileProvider(
    file: "D:\\Games\\Android\\XXXXXXX.apk",
    isCaseInsensitive: true,
    versions: new VersionContainer(EGame.GAME_UE4_LATEST));

Streamed _🪲

The streamed file provider is a built-in file provider specifically designed for accessing archives within a remote directory, a manifest file, or any data source that provides stream access to these archives, while offering flexibility in handling different project requirements. Thus, the provider does not automatically register archives, you need to manually do so using the provider.RegisterVfs method, so that the provider can access and work with the packages contained within these archives.

var provider = new StreamedFileProvider(
    liveGame: "XXXXXXX",    // can be useful in some cases
    isCaseInsensitive: true,
    versions: new VersionContainer(EGame.GAME_UE4_LATEST));

foreach (var archive in manifestInfo.Archives)
{
    provider.RegisterVfs(
        file: archive.GetFullName(),
        stream: new[] { archive.GetStream() });
}

Archive Abstraction _🪲

The AbstractVfsFileProvider provides a flexible abstraction for customizing archive initialization within CUE4Parse. This initialization process involves providing the necessary archives to the provider, enabling access to the packages contained within them.

To properly initialize your custom provider, follow these steps:

1. Populate the _requiredKeys dictionary with the GUIDs of encrypted archives.
2. Populate the _unloadedVfs dictionary with any type of archives readers that inherits from IAesVfsReader.

You can utilize built-in methods to do that, like RegisterVfs, which offer different parameters to suit your specific needs. However, you are not limited to these methods and can create your own implementation. By following these steps, your custom provider will be appropriately configured and ready to work with the provided archives.

public class CustomVfsFileProvider : AbstractVfsFileProvider
{
    public override void Initialize()
    {
        foreach (var file in Directory.GetFiles(@"D:\\Games\\PC\\XXXXXXX\\XXXXXXX\\Content\\Paks"))
        {
            RegisterVfs(file);
        }
    }

    // Implement custom functionality here
}

If you require complete customization, you can inherit from the IVfsFileProvider interface instead.

Package Abstraction _🪲

TODO

---

Please note that the provided examples utilize an arbitrary version container. It is important to set up the versioning settings according to your specific requirements to ensure proper parsing of archives and packages. For more information about versioning settings, please refer to the documentation here.

To ensure the proper initialization of built-in providers, it is recommended to invoke the Initialize method. This approach allows developers to have control over when the scanning of archives occurs, rather than performing it within a constructor. It is worth noting that both the default and APK file providers have the capability to load external packages as long as they are located within the specified directory or APK file.

The next section will provide guidance on mounting archives to make the packages contained within them accessible.

_{Please refer to the respective source code files linked above (🪲) for more detailed information and implementation specifics.}