UnityWebFileSystem

UnityWebFileSystem is a Unity package that provides access to the Web File System API from Unity.

This package enables Unity WebGL applications to interact with the user's local file system through modern browser APIs, allowing file reading, writing, and directory operations with user permission.

Requirements

• Unity 6000.0 or later
• UniTask package
• Modern browser with File System API support

Installation

Via Unity Package Manager

1. Open the Package Manager window
2. Click the + button and select "Add package from git URL"
3. Enter the following URL: https://github.com/yaegaki/UnityWebFileSystem.git?path=UnityWebFileSystem/Assets/UnityWebFileSystem

Assembly Definition Setup

If your project uses Assembly Definition files (.asmdef), you need to add a reference to UnityWebFileSystem.Generic

Usage

Basic File Operations

using UnityWebFileSystem.Generic;
using Cysharp.Threading.Tasks;
using System.Text;

// Open a file picker and read file content
// Note: ShowOpenSingleFilePickerAsync is only available in WebGL builds and Unity Editor
async UniTask ReadFileExample(CancellationToken cancellationToken)
{
    using var fileHandle = await GenericFileSystem.ShowOpenSingleFilePickerAsync(cancellationToken);

    using var file = await fileHandle.GetFileAsync(cancellationToken);
    var bytes = await file.BytesAsync(cancellationToken);
    var text = Encoding.UTF8.GetString(bytes);

    Debug.Log($"File: {file.Name()}, Size: {file.Size()}, Content: {text}");
}

Directory Operations

// Select a directory and enumerate its contents
// Note: ShowDirectoryPicker is only available in WebGL builds and Unity Editor
async UniTask EnumerateDirectoryExample(CancellationToken cancellationToken)
{
    using var directory = await GenericFileSystem.ShowDirectoryPickerAsync(cancellationToken);
    
    await foreach (var entry in directory.EntriesAsync(cancellationToken))
    {
        using var _ = entry.Handle;
        
        if (entry.Handle is GenericFileSystemFileHandle fileHandle)
        {
            Debug.Log($"File: {entry.Name}");
        }
        else if (entry.Handle is GenericFileSystemDirectoryHandle dirHandle)
        {
            Debug.Log($"Directory: {entry.Name}");
        }
    }
}

Writing Files

// Create and write to a file
async UniTask WriteFileExample(CancellationToken cancellationToken)
{
    using var directory = await GenericFileSystem.ShowDirectoryPickerAsync(
        new ShowDirectoryPickerOptions
        {
            mode = ShowDirectoryPickerOptions.Mode.ReadWrite
        }, 
        cancellationToken
    );
    
    // Get or create a file handle
    using var fileHandle = await directory.GetFileHandleAsync("example.txt", true, cancellationToken);
    
    // Create a writable stream
    using var writable = await fileHandle.CreateWritableAsync(cancellationToken);
    
    // Write data
    var data = Encoding.UTF8.GetBytes("Hello, World!");
    await writable.WriteAsync(data, cancellationToken);
    
    // Close the file and write the contents to disk
    await writable.CloseAsync(cancellationToken);
}

Origin Private File System (OPFS)

Writing to OPFS

// Access the origin private file system and write data
// Note: In WebGL, this uses OPFS. In other platforms (Editor/Standalone), 
// it uses Application.persistentDataPath
async UniTask WriteToOPFSExample(CancellationToken cancellationToken)
{
    using var directory = await GenericFileSystem.GetDirectoryAsync(cancellationToken);
    
    // Create subdirectory
    using var subDir = await directory.GetDirectoryHandleAsync("mydata", true, cancellationToken);
    
    // Create a file
    using var fileHandle = await subDir.GetFileHandleAsync("data.bin", true, cancellationToken);
    
    // Write data
    using var writable = await fileHandle.CreateWritableAsync(cancellationToken);
    await writable.WriteAsync(new byte[] { 1, 2, 3, 4 }, cancellationToken);
    await writable.CloseAsync(cancellationToken);

    Debug.Log("Data written to OPFS");
}

Reading from OPFS

// Read data from the origin private file system
async UniTask ReadFromOPFSExample(CancellationToken cancellationToken)
{
    using var directory = await GenericFileSystem.GetDirectoryAsync(cancellationToken);
    
    // Access subdirectory
    using var subDir = await directory.GetDirectoryHandleAsync("mydata", false, cancellationToken);
    
    // Get file handle
    using var fileHandle = await subDir.GetFileHandleAsync("data.bin", false, cancellationToken);
    
    // Read file content
    using var file = await fileHandle.GetFileAsync(cancellationToken);
    var bytes = await file.BytesAsync(cancellationToken);
    
    Debug.Log($"Read {bytes.Length} bytes from OPFS: {string.Join(", ", bytes)}");
}

Browser Compatibility

The File System API requires a modern browser.

See the MDN documentation for the latest compatibility information.

License

MIT