Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

collectionproxy1 new

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

Functions

collectionproxy.get_resources(collectionproxy: Url | string | Hash): string[]

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.

function print_resources(self: unknown, cproxy: Url) {
  const resources = collectionproxy.get_resources(cproxy);
  for (const v of resources) {
    print(`Resource: ${v}`);
  }
}
local function print_resources(self, cproxy)
    local resources = collectionproxy.get_resources(cproxy)
    for _, v in ipairs(resources) do
        print("Resource: " .. v)
    end
end

Parameters

  • collectionproxy: Url | string | Hash — the collectionproxy to check for resources.

Returns

  • resources: string[] — the resources, or an empty list if the collection was not excluded.

collectionproxy.load(url: string | Hash | Url, options: {} | undefined, callback: (self: unknown, message_id: Hash, message: collectionproxy.LoadData, sender: Url) => void): voidN

  • Since Defold 1.13.1

Loads the collection referenced by a collection proxy. The proxy is also initialized and the callback receives proxy_loading, proxy_ready, or proxy_error messages.

collectionproxy.load("#proxy", undefined, (self, message_id, message, sender) => {
  if (message_id === hash("proxy_ready")) {
    print("proxy is ready");
  } else if (message_id === hash("proxy_loading")) {
    print("progress", message.progress);
  } else if (message_id === hash("proxy_error")) {
    print("error", message.code);
  }
});
collectionproxy.load("#proxy", nil, function(self, message_id, message, sender)
    if message_id == hash("proxy_ready") then
        print("proxy is ready")
    elseif message_id == hash("proxy_loading") then
        print("progress", message.progress)
    elseif message_id == hash("proxy_error") then
        print("error", message.code)
    end
end)

Parameters

  • url: string | Hash | Url — the collection proxy component
  • options: {} | undefined — options table, currently unused
  • callback: (self: unknown, message_id: Hash, message: collectionproxy.LoadData, sender: Url) => void — callback

collectionproxy.set_collection(url: string | Hash | Url, prototype: string | undefined): LuaMultiReturn<[boolean, collectionproxy.Result | undefined]>

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.

// The example assumes the script belongs to an instance with a
// collection-proxy-component with id "proxy".
const [ok, error] = collectionproxy.set_collection("/go#collectionproxy", "/LU/3.collectionc");
if (ok) {
  print("The collection has been changed to /LU/3.collectionc");
} else {
  print("Error changing collection to /LU/3.collectionc ", error);
}
msg.post("/go#collectionproxy", "load");
msg.post("/go#collectionproxy", "init");
msg.post("/go#collectionproxy", "enable");
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")

Parameters

  • url: string | Hash | Url — the collection proxy component
  • prototype: string | undefined — the path to the new collection, or nil

Returns

  • success: boolean — collection change was successful
  • code: collectionproxy.Result | undefined — the failure reason

Constants

collectionproxy.RESULT_ALREADY_LOADED: number & { readonly __brand: "collectionproxy.RESULT_ALREADY_LOADED" }

The collection proxy is already loaded, so its collection cannot be changed.

collectionproxy.RESULT_LOADING: number & { readonly __brand: "collectionproxy.RESULT_LOADING" }

The collection proxy is loading, so its collection cannot be changed.

collectionproxy.RESULT_NOT_EXCLUDED: number & { readonly __brand: "collectionproxy.RESULT_NOT_EXCLUDED" }

The collection proxy is not excluded from the bundle; only excluded proxies can change collections.

Types

interface collectionproxy.LoadData { progress?: number; code?: number; }

type collectionproxy.Result = typeof collectionproxy.RESULT_ALREADY_LOADED | typeof collectionproxy.RESULT_LOADING | typeof collectionproxy.RESULT_NOT_EXCLUDED

type collectionproxy.TimeStepMode = 0 | 1

On this page