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:
settings = { plugins = { ["plugin.onDemandResources"] = { publisherId = "com.coronalabs", supportedPlatforms = { tvos=true } }, }, }
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):
settings = { tvos = { onDemandResources = { { tag="introMusic", resource="intro.mp4", type="prefetch" }, { tag="imgTutorial", resource="img/tutorial", type="install" }, { tag="imgL2", resource="img/level2" }, }, }, }
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.
Any tag which isn’t designated as "prefetch" or "install" will need to be explicitly requested by the app at a logical point during its 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.
-- Require the plugin local odr = require( "plugin.onDemandResources" ) -- On-demand resources listener function local function odrListener( event ) if not ( event.isError ) then print( "Resources for tag '" .. event.tag .. "' downloaded" ) else print( "ERROR: errorCode = " .. tostring(event.errorCode) ) end end -- Request image resources for second level odr.request( "imgL2", true, odrListener )
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:
local odr = require( "plugin.onDemandResources" ) -- On-demand resources listener function local function odrListener( event ) if ( event.isError ) then -- Resources have not been downloaded. You need to request them. end end -- Request image resources for second level odr.request( "imgL2", false, odrListener )
Important notes
- All on-demand resources are subject to be evicted by the operating system if it needs space, so even your
install– andprefetch-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 512 megabytes, but even smaller tagged packages are recommended.
- 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.