Collection proxy API documentation

Version: stable

Messages for controlling and interacting with collection proxies which are used to dynamically load collections into the runtime.

FUNCTION
collectionproxy.missing_resources()

return an indexed table of missing resources for a collection proxy

MESSAGE
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.missing_resources()

collectionproxy.missing_resources(collectionproxy)

return an indexed table 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)
    self.manifest = resource.get_current_manifest()
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

Messages

async_load

tells a collection proxy to start asynchronous loading of the referenced collection

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

tells a collection proxy to disable the referenced collection

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

tells a collection proxy to enable the referenced collection

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

tells a collection proxy to finalize the referenced collection

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

tells a collection proxy to initialize the loaded collection

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

tells a collection proxy to start loading the referenced collection

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

reports that a collection proxy has loaded its referenced collection

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

reports that a collection proxy has unloaded its referenced collection

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

sets the time-step for update

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

tells a collection proxy to start unloading the referenced collection

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