onDemandResources.request()

Type Function
Return value none
Revision Release 2024.3703
Keywords on-demand resources, onDemandResources, request
See also onDemandResources.setEventListener()
onDemandResources.*

Overview

This is the core function of the plugin. Calling it initiates a request to access on-demand resources configured within build.settings.

Important

  • Resources must be available before you attempt to use them. This function 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 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).

Note

Remember that on-demand resources requests are designed to work in the background, so you can request multiple resources at logical times within the app flow. For example, if a player is progressing through a game tutorial, you may request resources required for further instruction sometime in advance of using them, not just directly before you intend to use them.

Syntax

onDemandResources.request( tag [, download] [, listener] )
tag (required)

String. Tag for which to request on-demand resources.

download (optional)

Boolean. Indicates if downloading of the resource(s) should begin if they are not locally available. Default value is true. If you simply want to check if the associated resources are locally available, pass false and this function will invoke an on-demand resources event almost immediately.

listener (optional)

Listener. Listener function that will receive an on-demand resources event when the resources are accessible, or if an error occurs. This listener will only receive events specifically associated with this request — if you wish to set up a broader listener function to handle general on-demand resources calls, use onDemandResources.setEventListener().

Examples

Check Resources
local odr = require( "plugin.onDemandResources" )

-- On-demand resources listener function
local function odrListener( event )
    if ( event .isError ) then
        -- Resources are not downloaded; see next example for download usage
    end
end

-- Check image resources for second level
odr.request( "imgL2", false, odrListener )  -- Pass 'false' as second argument to check (not download)
Download Resources
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 first level
odr.request( "imgL1", true, odrListener )
Progress Indicator
local odr = require( "plugin.onDemandResources" )
local composer = require( "composer" )
local widget = require( "widget" )

local levelTag = "assetsL1"
local levelScene = "level1"

-- This function will indicate progress via a widget and go to scene when done
local function downloadResources( tag )

    -- Create progress bar
    local progressBar = widget.newProgressView( { x=160, y=240, width=120, isAnimated=false } )
    progressBar:setProgress( 0 )

    -- Runtime listener to update progress bar
    local function updateProgress()
        progressBar:setProgress( odr.progress(tag) )
    end
    Runtime:addEventListener( "enterFrame", updateProgress )

    -- Now, download resources with "urgent" priority
    odr.request( tag, true,
        function( event )
            -- Remove progress bar
            Runtime:removeEventListener( "enterFrame", updateProgress )
            progressBar:removeSelf()
            progressBar = nil
            -- Proceed to level scene
            if not ( event.isError ) then
                composer.gotoScene( levelScene )
            end
        end )
    odr.setDownloadPriority( tag, "urgent" )
end

-- First, simply check if resources are already downloaded
odr.request( levelTag, false,
    function( event )
        if not ( event.isError ) then
            -- Resources already downloaded; proceed to level scene
            composer.gotoScene( levelScene )
        else
            -- Resources must be downloaded; call download function above
            downloadResources( levelTag )
        end
    end )