Apple “on-demand resources” plugin now available

23 March 2016

Apple “on-demand resources” plugin now available

Corona Labs is pleased to announce the availability of the on-demand resources plugin, currently supported on tvOS. Similar in concept to Android expansion files (but functionally quite different), on-demand resources allow you to specify parts/assets of your app which can be downloaded when needed. This is especially important for Apple TV because Apple limits tvOS apps to a maximum size of 200 megabytes and they provide no local storage for data. Instead, they expect developers to use on-demand resources to manage which assets are available at which points in the app.

Setup

Like any plugin, begin by including it in your build.settings:

Defining resources

To make on-demand resources work, you must designate various files or folders by “tags” inside the tvos → onDemandResources table of build.settings. Each entry is itself a table containing two required key-value pairs: the tag name (tag) and the file/folder it refers to (resource):

In addition, you can specify a download priority for each tag. This is done via the type key with one of the following values:

• "install" — Use this for critical files that may be required immediately when the app first launches. These resources download in parallel with the app download itself, however they are not bundled in the app package as persistent resources.
• "prefetch" — These resources will start downloading in the background after the app finishes downloading.
• No type — These are resources you fetch when you need them.

Regardless of the type value, you need to explicitly request the tag before you can use it. Tags that don’t have a type are requested at a logical point during the app flow.

Requesting content

To download a resource file/folder when needed, for example assets for the second level after the player completes the first level, simply call the onDemandResources.request() function. This may be considered the “core” function of the plugin, as it’s required before you can access on-demand resources.

One of the most important aspects of onDemandResources.request() is the second parameter: a boolean true or false. Setting this to true (or omitting it, since true is the default) tells Corona to begin downloading the resources immediately.

By comparison, if you set this parameter to false, Corona simply checks if the resources are already downloaded:

Important notes

• All on-demand resources are subject to be evicted by the operating system if it needs space, so even your install– and prefetch-based resources should be checked for availability before you attempt to use them. If they don’t exist, you will need to request/download them again.
  • Large downloads take time, so you may consider more tags with smaller overall download sizes. Apple advises keeping tagged resources under 64 megabytes. The maximum size for a tag is 512 megabytes.
• You have to use a service like Apple’s TestFlight to test on-demand resources — you cannot simply load the app directly onto your test device. This is the only way Apple can actually deliver the various resources from their servers.

Conclusion

On-demand resources can be essential for developing tvOS games and apps, and Corona’s plugin provides the necessary interface to Apple’s servers. To learn more, please see the documentation or discuss further in the Corona Forums.