Overview

Usage of on-demand resources can be essential for developing tvOS games and apps since there is a limit of 200 MB for the app bundle.

Essentially, on-demand resources allow you to split your app into parts and download specific assets/resources when you require them. This technique can also be utilized to minimize the app's initial download size and reduce the footprint size in the device's storage.

Tags

When using on-demand resources, you should separate parts of your app into downloadable packages and reference them with tags. Each tag can point to an individual resource (file) or a group of resources (folder). By default, these resources will be excluded from the app bundle and will be available only after the app is downloaded.

See the instructions below regarding configuration of on-demand resources/tags.

Important

Resources must be available before you attempt to use them. This is accomplished via onDemandResources.request() which can both check the availability of resources or download them. If the desired resources are not available, you should request their download and wait for a successful callback response before attempting to use them.

Once resources are successfully requested and downloaded, they can be safely accessed until the application is terminated.

Even though you can typically use on-demand resources as if they exist in your app's bundle, they are not physically there. Use system.pathForFile() to retrieve the actual path, or alternatively the convenience function onDemandResources.path(). This may be necessary when, for example, an on-demand resource is a text file (not an image) and io.open() is required to open the file and read its contents (guide).

Gotchas

You should not assign unique tags to both a folder and a nested folder within it. For example, if you assign a tag to assets/images, you should not assign a separate tag to assets/images/level1 because, inherently, the level1 resources are already included as part of the broader tag.

If the operating system requires storage space, it may automatically cycle through tags and evict downloaded content. By default, resources which have not been used recently will be prioritized for eviction, although you can manage eviction behavior with onDemandResources.setPreservationPriority().

On-demand resources only function in distributed apps. To test functionality prior to release, use a service such as TestFlight.

Project Settings

To use this plugin, add an entry into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase.

To configure on-demand resources, include the onDemandResources table within the tvos table of build.settings. This table should consist of a series of entries (tables) which define the packages for on-demand resources. Each of these tables must include a required tag key (string) and a required resource key (string) which can reference either a specific file or a folder containing multiple resources.

In addition, you can include an optional type key equal to either of these values:

"install" — These resources will be downloaded immediately when the app is downloaded from the App Store. This is useful for resources which may be required immediately when the app is first launched. In contrast to assets which are simply pre-bundled within your project folder for persistent availability, on-demand resources tagged with "install" may still be evicted from local storage at some point.

"prefetch" — These resources will begin to download in the background immediately after the app is downloaded from the App Store.