NativeFileSO

NativeFileSO adds native file import and export functionality across Windows, macOS, iOS and Android to your Unity project.

Features:

With all of the functionality that NativeFileSO can offer, there are still some limitations due to platform specific constraints, so please make sure to carefully read the section on requirements & limitations.

Setup

Setting up the asset requires relatively little work. After importing the package contents, you should have the following folder hierarchy inside of your Assets folder:

Assets/
|- ...
|- NativeFileSO/
|  |- Editor/
|  |- Prefabs/
|  |- Samples/
|  |- Scripts/
|- Plugins/
   |- ...
   |- NativeFileSO/
      |- Android/
      |- iOS/
      |- macOS/
      |- Windows/

In order for NativeFileSO to be able to function properly, it needs to know about certain system events (such as when the app enters the focused state or when it is launched). That's what the NativeFileSOUnityEvent prefab is for.

Simply drag and drop the NativeFileSOUnityEvent prefab from the NativeFileSO/Prefabs/ folder into your scene. This should be the first scene that is loaded when your game starts.

Setup file associations

If you are not planning to associate any file types with your app, you are done with the setup and you can open and export files through the interface provided by the NativeFileSO class as demostrated in the examples.

Otherwise, continue with the following steps:

Inside of your own MonoBehaviour class that you want to deal with associated files that the user is trying to open in your app, you need to subscribe to the FilesWereOpened event that is raised by the shared instance of the NativeFileSOMobile class.

using Keiwando.NFSO;

public class MyFileHandler : MonoBehaviour {

	void Start() {
		NativeFileSOMobile.shared.FilesWereOpened += delegate (OpenedFile[] files) {
			// Process the opened files
		};		
	}
}

For this behaviour to work reliably, we need to make sure that the FilesWereOpened event is never raised before we had a chance to subscribe to it. In the Unity editor, go to Edit > Project Settings > Script Execution Order, add Keiwando.NFSO.NativeFileSOUnityEvent to the list and assign it the value 32000.

You associate file types with your app by including them in the supportedFileTypes array in the SupportedFilePreferences.cs file. You can use the presets or create your own instances of the SupportedFileType class.

public static readonly SupportedFileType[] supportedFileTypes = {

	// Edit this list to include your desired file types

	SupportedFileType.JPEG,
	SupportedFileType.PlainText
	//SupportedFileType.Any
};

These files will be automatically associated with the iOS app, however, the Android plugin requires one additional step. After editing the supportedFileTypes array, wait for the Editor to compile the scripts and then click on the Tools > NativeFileSO > RefreshAndroidPlugin menu item. You will need to manually do this once each time you change the list of associated file types.

Also make sure to read the section on general requirements & limitations and adjust your project and build settings as described for each platform.

Examples

The NativeFileSO class provides the main interface for you to interact with the functionality on all platforms. The NativeFileSOMacWin class offers some additional functionality that is only available on desktop platforms, such as the ability to select file paths (without loading the file contents immediately).

All of the classes you need to interact with are contained in the Keiwando.NFSO namespace, so the following examples are assumed to contain a

using Keiwando.NFSO;

statement at the top of the file.

Visit the documentation for a more detailed reference of what each class shown here does.

Export a file

The following example demonstrates how to use the NativeFileSO class in order to copy/export a file from an existing path to a new location chosen by the user.

string path = "path/to/existing/fileToSave.txt";
string newFilename = "ExportedFile.txt";

FileToSave file = new FileToSave(path, newFilename, SupportedFileType.PlainText);

// Allows the user to choose a save location and saves the 
// file to that location
NativeFileSO.shared.SaveFile(file);

Open a single file

This snipped shows how to use the NativeFileSO class in order to let the user choose a text file and handle its loaded contents.

// We want the user to select a plain text file.
SupportedFileType[] supportedFileTypes = {
	SupportedFileType.PlainText
};

NativeFileSO.shared.OpenFile(supportedFileTypes,
  delegate (bool fileWasOpened, OpenedFile file) {
	if (fileWasOpened) {
		// Process the loaded contents of "file"
		Debug.Log(file.ToUTF8String());  
	} else {
		// The file selection was cancelled.	
	}
});

Screenshots

macOS

Windows

iOS

Android

Requirements & Limitations

Here are the main limitations and platform requirements for the asset that you should read and take into consideration before deciding on whether you would like to integrate NativeFileSO into your own project.

General

Windows

macOS

Android

iOS

Mobile (iOS + Android)