🗄️ FileKit

Improve loading time and and performance through file-streaming.

What is FileKit?

FileKit is one of the "secret sauces" Trail uses to make your games ultra-accessible. It is essentially a file streaming service but with ease of use in mind. No more worrying about versioning, compression, file duplications in memory and CDNs. All of this is handled by FileKit automatically for you.

WebGL and memory

In WebGL, the browser doesn't allow the game to access the file system. This means, when you are trying to load or write a file to disc the compiler emulates a virtual file system in memory. Consequently, the entirety of your game assets would be stored in memory and to top it off, whenever your game would request an asset, it would create a new copy of said asset as if "loading it into memory".
Combine this with the browser's enforcing a limit of 2GB RAM per tab and you can imagine how this is a big issue.

Game partitioning

The solution to the above problem is to partition your game.

The difference between a non-partitioned game (Game A) and a partitioned game (Game B)The difference between a non-partitioned game (Game A) and a partitioned game (Game B)

The difference between a non-partitioned game (Game A) and a partitioned game (Game B)

There are two ways to handle assets and content in a game. The first one is Game A's method; you bundle all your assets and all your content and they get downloaded when the player loads your game. Whenever you update any of your game content or assets, the user has to download the entire game every time.

In the second method, Game B's method; you divide your game's content and assets into multiple partitions (or bundles). You upload your base game (bare minimum content, assets and code) on the main server (where players download your game) and then you upload the rest to a secondary server that your game downloads when the user starts using the content.

You can see the second method used a lot in MMO (Massively Multiplayer Online) games. You download a small section of the game (likely the starter area) and as you go through that content, the game keeps downloading the rest of the content progressively to serve it as you need it.

📘

Our current target is to launch (a fully interactive experience, not an in-game progress bar) any game within 30 seconds or less.

As you can guess, the second method is what we recommend when publishing your games on Trail. Since Trail is web-based, loading times and performance are very important.
The second method allows the player to access the game faster (since they only download a smaller size content vs the entire game's catalog). It also helps with game performance (by loading only the necessary content in memory) and this something FileKit helps with immensely!

FileKit and Unity's Addressables

FileKit works really great with Unity's Addressables. Given you can use Addressables in one of two ways, FileKit behaves differently based on this:

  • If you are keeping your content local (using StreamingAssets folder) and loading your content/assets only when you need them, FileKit will detect this, host your assets on our CDN free of charge, auto-version it for you and compress it using Brotli. It will then remap all your asset loading code to FileKit to load them from our CDN and decompress them when needed automatically. This provides you with faster loading times of assets and less memory footprint.

  • If you are keeping your content on a CDN (be it Unity's or another), FileKit will detect this and not modify anything and keeps your references intact.

❗️

Async/Await

Unfortunately, Unity supports the main thread only on WebGL as per their documentation. This means you can't use Async/Await when loading your Addressables you'll need to perform this on the main thread. One way to do that is by using Coroutines.

FileKit and Resources Folder

We echo Unity's sentiment in trying to avoid using the Resources Folder as much as possible due to its issues. Instead, we recommend that you use FileKit directly.

Using FileKit directly

You can still use FileKit directly without resorting to neither Addressables nor the Resources folder. You can load a file directly by using FileKit.ReadFile and providing the path and name of the file you want to load.

// SDK must be initialized first before using FileKit.

// When the level is loaded, load the player's image.
private void OnMainLevelLoaded()
{
    FileKit.ReadFile("StreamingAssets/" + "Art/Avatars/player.png", DisplayAvatarIcon);
}

// A call back triggered when FileKit is done with loading the image, assign it to the correct UI element
private void DisplayAvatarIcon(Result result, byte[] data, int dataLength)
{
    if(result.IsOK()) {
       myimage.sprite = (Sprite) data;
    }
}

📘

Paths provided to FileKit.ReadFile

You might have noticed above that we provided the method ReadFile with the path StreamingAssets/. This is a special feature of ReadFile, whatever path is given, ReadFile will understand that this path is inside the Assets folder of your project and will look for the file there. You don't have to use any special path resolution tricks to find what you want.

🚧

FileKit Error handling

Sometimes when you're reading a file, you may encounter errors while doing that. We provided the Result enum to help you find out what the exact error is and resolve it. The three main issues you can encounter with FileKit are:

Result.FLKFileNotFound: This is when you're trying to load a file that does not exist. We recommend you double check the path and the filename you're reading.

Result.FLKFileTooBig: This happens when you're trying to load a file bigger than 4 TB.

Result.FLKBufferTooSmall: This happens when you're providing a smaller buffer than the information passed. Providing a larger buffer will resolve the issue.

Updated 5 months ago

🗄️ FileKit


Improve loading time and and performance through file-streaming.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.