DOCSEARCHbyAlgolia
Submit Docs

Better Streaming Assets

repository·master·Indexed 20 days ago

https://github.com/gwiazdorrr/betterstreamingassets

A Unity plugin (version 1.7.1) providing a uniform, thread-safe way to access Streaming Assets with minimal overhead. It is primarily optimized for Android to avoid inefficiencies of the legacy WWW class or Asset Bundle embedding. The API supports file and directory operations similar to System.IO, as well as synchronous and asynchronous Asset Bundle loading. Note that it does not support WebGL.

Tokens
1.3K
Snippets
5
Records
7
Agent score
22%

What's inside Better Streaming Assets

  1. Use relative paths for Streaming Assets

    master

    All paths provided to the API are relative to the StreamingAssets directory.

    If your file structure is:

    • <project>/Assets/StreamingAssets/foo.bar
    • <project>/Assets/StreamingAssets/dir/foo.bar

    You should use:

    • foo.bar (or /foo.bar)
    • dir/foo.bar (or /dir/foo.bar)

  2. Android constraints: Filenames and Characters

    master

    When targeting Android (especially with App Bundles/.aab), follow these rules to avoid bugs or unexpected file compression:

    1. Use lowercase filenames: Keep all file names in StreamingAssets lowercase.
    2. Avoid non-ASCII characters: Do not use non-ASCII characters in file names or in the path of extension-less files. Using them may cause the file to be compressed, which can break access.

    Note on WebGL: This plugin currently does not support WebGL.

  4. Install Better Streaming Assets

    master

    You can install this plugin using one of the following three methods:

    1. Unity Package Manager: Select "Add package from git URL..." and use: https://github.com/gwiazdorrr/BetterStreamingAssets.git
    2. Manual Installation: Clone the repository and copy the Runtime directory into your Unity project.
    3. Asset Store: Download the latest release from the Unity Asset Store.
    https://github.com/gwiazdorrr/BetterStreamingAssets.git

  5. Suppress Android compression false-positives

    master

    On Android, the tool logs errors if it finds compressed files in the assets directory (which might indicate a configuration error). If you have custom plugin files in assets that are intentionally compressed and you want to prevent these logs, you have two options:

    Option 1: Use the IsAndroidCompressedStreamingAsset event

    Add an event handler in the same assembly as BetterStreamingAssets:

    BetterStreamingAssets.IsAndroidCompressedStreamingAsset += (path) =>
{
    if (path == "assets/my_custom_plugin_settings.json")
    {
        return false; // Not a Streaming Asset, ignore compression error
    }
    return true; // It is a Streaming Asset, log error if compressed
};

    Option 2: Implement the partial method

    Implement the partial method in the same asmdef as BetterStreamingAssets:

    partial class BetterStreamingAssets
{
    static partial void AndroidIsCompressedFileStreamingAsset(string path, ref bool result)
    {
        if (path == "assets/my_custom_plugin_settings.json")
        {
            result = false;
        }
    }
}
    BetterStreamingAssets.IsAndroidCompressedStreamingAsset += (path) =>
{
    if (path == "assets/my_custom_plugin_settings.json")
    {
        return false;
    }
    return true;
};

  6. Read files and directories

    master

    The API is based on System.IO.File and System.IO.Directory patterns. Most methods can be called from any thread, provided the resulting data processing (like a constructor) doesn't make Unity engine calls.

    Common File Operations

    • BetterStreamingAssets.FileExists(path): Checks if a file exists.
    • BetterStreamingAssets.ReadAllBytes(path): Reads the entire file into a byte[].
    • BetterStreamingAssets.OpenRead(path): Returns a Stream for reading. This is useful for deserialization or partial reads.

    Directory Operations

    • BetterStreamingAssets.DirectoryExists(path): Checks if a directory exists.
    • BetterStreamingAssets.GetFiles(path, searchPattern, searchOption): Returns an array of file paths. searchOption uses SearchOption.AllDirectories or SearchOption.TopDirectoryOnly.
    // Read all bytes
byte[] data = BetterStreamingAssets.ReadAllBytes("Foo/bar.data");

// Open as stream
using (var stream = BetterStreamingAssets.OpenRead("Foo/bar.data"))
{
    // Use stream...
}

// List files
string[] paths = BetterStreamingAssets.GetFiles("Config", "*.xml", SearchOption.AllDirectories);

// Check directory
bool exists = BetterStreamingAssets.DirectoryExists("Config");

  7. Load Asset Bundles

    master

    You can load Asset Bundles from Streaming Assets. Note that these operations must be performed on the main thread.

    • BetterStreamingAssets.LoadAssetBundle(path): Synchronous loading.
    • BetterStreamingAssets.LoadAssetBundleAsync(path): Asynchronous loading (returns an async operation).
    // Synchronous
var bundle = BetterStreamingAssets.LoadAssetBundle(path);

// Async
var bundleOp = BetterStreamingAssets.LoadAssetBundleAsync(path);