Collection proxy API documentation

Version: alpha

FUNCTIONS
collectionproxy.get_resources() return an indexed table of all the resources of a collection proxy
collectionproxy.missing_resources() return an array of missing resources for a collection proxy
collectionproxy.set_collection() changes the collection for a collection proxy.
CONSTANTS
collectionproxy.RESULT_ALREADY_LOADED collection proxy is already loaded
collectionproxy.RESULT_LOADING collection proxy is loading now
collectionproxy.RESULT_NOT_EXCLUDED collection proxy isn't excluded
MESSAGES
async_load tells a collection proxy to start asynchronous loading of the referenced collection
disable tells a collection proxy to disable the referenced collection
enable tells a collection proxy to enable the referenced collection
final tells a collection proxy to finalize the referenced collection
init tells a collection proxy to initialize the loaded collection
load tells a collection proxy to start loading the referenced collection
proxy_loaded reports that a collection proxy has loaded its referenced collection
proxy_unloaded reports that a collection proxy has unloaded its referenced collection
set_time_step sets the time-step for update
unload tells a collection proxy to start unloading the referenced collection

Functions

collectionproxy.get_resources()

collectionproxy.get_resources(collectionproxy)

return an indexed table of resources for a collection proxy where the referenced collection has been excluded using LiveUpdate. Each entry is a hexadecimal string that represents the data of the specific resource. This representation corresponds with the filename for each individual resource that is exported when you bundle an application with LiveUpdate functionality.

PARAMETERS

collectionproxy url the collectionproxy to check for resources.

RETURNS

resources table the resources, or an empty list if the collection was not excluded.

EXAMPLES

local function print_resources(self, cproxy)
    local resources = collectionproxy.get_resources(cproxy)
    for _, v in ipairs(resources) do
        print("Resource: " .. v)
    end
end

collectionproxy.missing_resources()

collectionproxy.missing_resources(collectionproxy)

return an array of missing resources for a collection proxy. Each entry is a hexadecimal string that represents the data of the specific resource. This representation corresponds with the filename for each individual resource that is exported when you bundle an application with LiveUpdate functionality. It should be considered good practise to always check whether or not there are any missing resources in a collection proxy before attempting to load the collection proxy.

PARAMETERS

collectionproxy url the collectionproxy to check for missing resources.

RETURNS

resources table the missing resources

EXAMPLES

function init(self)
end

local function callback(self, id, response)
    local expected = self.resources[id]
    if response ~= nil and response.status == 200 then
        print("Successfully downloaded resource: " .. expected)
        resource.store_resource(response.response)
    else
        print("Failed to download resource: " .. expected)
        -- error handling
    end
end

local function download_resources(self, cproxy)
    self.resources = {}
    local resources = collectionproxy.missing_resources(cproxy)
    for _, v in ipairs(resources) do
        print("Downloading resource: " .. v)

        local uri = "http://example.defold.com/" .. v
        local id = http.request(uri, "GET", callback)
        self.resources[id] = v
    end
end

collectionproxy.set_collection()

collectionproxy.set_collection([url],[prototype])

The collection should be loaded by the collection proxy. Setting the collection to "nil" will revert it back to the original collection. The collection proxy shouldn't be loaded and should have the 'Exclude' checkbox checked. This functionality is designed to simplify the management of Live Update resources.

PARAMETERS

[url] string, hash, url the collection proxy component
[prototype] string, nil the path to the new collection, or nil

RETURNS

success boolean collection change was successful
code number one of the collectionproxy.RESULT_* codes if unsuccessful

EXAMPLES

The example assume the script belongs to an instance with collection-proxy-component with id "proxy". 
local ok, error = collectionproxy.set_collection("/go#collectionproxy", "/LU/3.collectionc")
 if ok then
     print("The collection has been changed to /LU/3.collectionc")
 else
     print("Error changing collection to /LU/3.collectionc ", error)
 end
 msg.post("/go#collectionproxy", "load")
 msg.post("/go#collectionproxy", "init")
 msg.post("/go#collectionproxy", "enable")

Constants

collectionproxy.RESULT_ALREADY_LOADED

It's impossible to change the collection if the collection is already loaded.

collectionproxy.RESULT_LOADING

It's impossible to change the collection while the collection proxy is loading.

collectionproxy.RESULT_NOT_EXCLUDED

It's impossible to change the collection for a proxy that isn't excluded.

Messages

async_load

Post this message to a collection-proxy-component to start background loading of the referenced collection. When the loading has completed, the message proxy_loaded will be sent back to the script. A loaded collection must be initialized (message init) and enabled (message enable) in order to be simulated and drawn.

EXAMPLES

In this example we use a collection proxy to load/unload a level (collection). The example assume the script belongs to an instance with collection-proxy-component with id "proxy". 
function on_message(self, message_id, message, sender)
    if message_id == hash("start_level") then
        -- some script tells us to start loading the level
        msg.post("#proxy", "async_load")
        -- store sender for later notification
        self.loader = sender
    elseif message_id == hash("proxy_loaded") then
        -- enable the collection and let the loader know
        msg.post(sender, "enable")
        msg.post(self.loader, message_id)
    end
end

disable

Post this message to a collection-proxy-component to disable the referenced collection, which in turn disables the contained game objects and components.

EXAMPLES

In this example we use a collection proxy to load/unload a level (collection). The example assumes the script belongs to an instance with a collection-proxy-component with id "proxy". 
function on_message(self, message_id, message, sender)
    if message_id == hash("end_level") then
        local proxy = msg.url("#proxy")
        msg.post(proxy, "disable")
        msg.post(proxy, "final")
        msg.post(proxy, "unload")
        -- store sender for later notification
        self.unloader = sender
    elseif message_id == hash("proxy_unloaded") then
        -- let unloader know
        msg.post(self.unloader, "level_ended")
    end
end

enable

Post this message to a collection-proxy-component to enable the referenced collection, which in turn enables the contained game objects and components. If the referenced collection was not initialized prior to this call, it will automatically be initialized.

EXAMPLES

In this example we use a collection proxy to load/unload a level (collection). The example assume the script belongs to an instance with collection-proxy-component with id "proxy". 
function on_message(self, message_id, message, sender)
    if message_id == hash("start_level") then
        -- some script tells us to start loading the level
        msg.post("#proxy", "load")
        -- store sender for later notification
        self.loader = sender
    elseif message_id == hash("proxy_loaded") then
        -- enable the collection and let the loader know
        msg.post(sender, "enable")
        msg.post(self.loader, "level_started")
    end
end

final

Post this message to a collection-proxy-component to finalize the referenced collection, which in turn finalizes the contained game objects and components.

EXAMPLES

In this example we use a collection proxy to load/unload a level (collection). The example assumes the script belongs to an instance with a collection-proxy-component with id "proxy". 
function on_message(self, message_id, message, sender)
    if message_id == hash("end_level") then
        local proxy = msg.url("#proxy")
        msg.post(proxy, "disable")
        msg.post(proxy, "final")
        msg.post(proxy, "unload")
        -- store sender for later notification
        self.unloader = sender
    elseif message_id == hash("proxy_unloaded") then
        -- let unloader know
        msg.post(self.unloader, "level_ended")
    end
end

init

Post this message to a collection-proxy-component to initialize the game objects and components in the referenced collection. Sending enable to an uninitialized collection proxy automatically initializes it. The init message simply provides a higher level of control.

EXAMPLES

In this example we use a collection proxy to load/unload a level (collection). The example assume the script belongs to an instance with collection-proxy-component with id "proxy". 
function on_message(self, message_id, message, sender)
    if message_id == hash("load_level") then
        -- some script tells us to start loading the level
        msg.post("#proxy", "load")
        -- store sender for later notification
        self.loader = sender
    elseif message_id == hash("proxy_loaded") then
        -- only initialize the proxy at this point since we want to enable it at a later time for some reason
        msg.post(sender, "init")
        -- let loader know
        msg.post(self.loader, message_id)
    end
end

load

Post this message to a collection-proxy-component to start the loading of the referenced collection. When the loading has completed, the message proxy_loaded will be sent back to the script. A loaded collection must be initialized (message init) and enabled (message enable) in order to be simulated and drawn.

EXAMPLES

In this example we use a collection proxy to load/unload a level (collection). The example assume the script belongs to an instance with collection-proxy-component with id "proxy". 
function on_message(self, message_id, message, sender)
    if message_id == hash("start_level") then
        -- some script tells us to start loading the level
        msg.post("#proxy", "load")
        -- store sender for later notification
        self.loader = sender
    elseif message_id == hash("proxy_loaded") then
        -- enable the collection and let the loader know
        msg.post(sender, "enable")
        msg.post(self.loader, message_id)
    end
end

proxy_loaded

This message is sent back to the script that initiated a collection proxy load when the referenced collection is loaded. See documentation for load for examples how to use.

proxy_unloaded

This message is sent back to the script that initiated an unload with a collection proxy when the referenced collection is unloaded. See documentation for unload for examples how to use.

set_time_step

Post this message to a collection-proxy-component to modify the time-step used when updating the collection controlled by the proxy. The time-step is modified by a scaling factor and can be incremented either continuously or in discrete steps. The continuous mode can be used for slow-motion or fast-forward effects. The discrete mode is only useful when scaling the time-step to pass slower than real time (factor is below 1). The time-step will then be set to 0 for as many frames as the scaling demands and then take on the full real-time-step for one frame, to simulate pulses. E.g. if factor is set to 0.1 the time-step would be 0 for 9 frames, then be 1/60 for one frame, 0 for 9 frames, and so on. The result in practice is that the game looks like it's updated at a much lower frequency than 60 Hz, which can be useful for debugging when each frame needs to be inspected.

factor number time-step scaling factor
mode number time-step mode: 0 for continuous and 1 for discrete

EXAMPLES

The examples assumes the script belongs to an instance with a collection-proxy-component with id "proxy". Update the collection twice as fast: 
msg.post("#proxy", "set_time_step", {factor = 2, mode = 0})
Update the collection twice as slow: 
msg.post("#proxy", "set_time_step", {factor = 0.5, mode = 0})
Simulate 1 FPS for the collection: 
msg.post("#proxy", "set_time_step", {factor = 1/60, mode = 1})

unload

Post this message to a collection-proxy-component to start the unloading of the referenced collection. When the unloading has completed, the message proxy_unloaded will be sent back to the script.

EXAMPLES

In this example we use a collection proxy to load/unload a level (collection). The example assumes the script belongs to an instance with a collection-proxy-component with id "proxy". 
function on_message(self, message_id, message, sender)
    if message_id == hash("end_level") then
        local proxy = msg.url("#proxy")
        msg.post(proxy, "disable")
        msg.post(proxy, "final")
        msg.post(proxy, "unload")
        -- store sender for later notification
        self.unloader = sender
    elseif message_id == hash("proxy_unloaded") then
        -- let unloader know
        msg.post(self.unloader, "level_ended")
    end
end