Skip to Content
defold-typescript libraries
HGPoint

HGPoint/defold_live_unbundler/live_unbundler

Live Update helper for splitting large archives into smaller dependency-aware chunks, and downloading and mounting them at runtime.

  • GitHub: HGPoint/defold_live_unbundler — pinned to 3.0
    1. Pick a release from HGPoint/defold_live_unbundler releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as live_unbundler from "live_unbundler"

Functions

set_log_function(fn: (level: number, message: string) => void)

Assign a project logger. Signature: function(level, message), where level is one of M.DEBUG..M.FATAL. Optional — defaults to a no-op.

Parameters

  • fn: (level: number, message: string) => void

set_platform_supported(supported: boolean)

Parameters

  • supported: boolean

set_save_cache_key(key: string)

Sets the save-file key used to persist the list of downloaded archives. Must be called before M.init. The value is whatever sys.get_save_file(...) returns; keep it stable across releases so existing installs keep their saved state.

Parameters

  • key: string

set_bench_log(enabled: boolean)

Parameters

  • enabled: boolean

bench_mark(event: string, details?: string | undefined)

Parameters

  • event: string
  • details?: string | undefined

set_verify_hashes(enabled: boolean)

Parameters

  • enabled: boolean

set_parallel_downloads(count?: number | undefined)

Parameters

  • count?: number | undefined

get_parallel_downloads(): number

Returns

  • number

set_post_budget(sec?: number | undefined)

Parameters

  • sec?: number | undefined

get_post_budget(): number

Returns

  • number

has_module(module_name: string): boolean

Parameters

  • module_name: string

Returns

  • boolean

is_module_loaded(module_name: string): boolean

Parameters

  • module_name: string

Returns

  • boolean

init(options: liveupdater_init_options, cb: (success: boolean, error_text: string | undefined) => void, module_available_fn?: ((module_name: string) => boolean) | undefined)

Parameters

  • options: liveupdater_init_options
  • cb: (success: boolean, error_text: string | undefined) => void
  • module_available_fn?: ((module_name: string) => boolean) | undefined — predicate gating non by_request modules; defaults to always-available

add_listener(url?: Url | undefined)

Parameters

  • url?: Url | undefined

remove_listener(url?: Url | undefined)

Parameters

  • url?: Url | undefined

get_module_progress(module_name: string, module?: liveupdater_module | undefined): liveupdater_module_progress | undefined

Parameters

  • module_name: string
  • module?: liveupdater_module | undefined

Returns

  • liveupdater_module_progress | undefined

is_liveupdate_loaded(): boolean

Returns

  • boolean

get_downloadable_files(): LuaTable<string, liveupdater_file_progress>

Returns

  • LuaTable<string, liveupdater_file_progress>

get_downloadable_missing_files(): LuaTable<string, string>

Returns

  • LuaTable<string, string>

get_modules_download_progress(module_names: string | string[]): liveupdater_download_progress

Byte-based progress for a module or a set of modules, with a per-resolution breakdown in the low/high fields. Shared dependency archives are counted once per set; an archive identical in both manifests counts toward the resolution counted first (for RES_BOTH that is lowres — the pass that actually downloads it). Anchored to the download queue: an archive counts as downloaded when nothing for it is pending, so the result reaches 100 exactly when the set's downloads drain. For by_request modules that were not requested yet, the future queue content is predicted from the same rules enqueue_modules uses; that prediction can dip for a moment while a shared archive is remounted to its highres copy, it recovers on the next mount.

Parameters

  • module_names: string | string[]

Returns

  • liveupdater_download_progress

get_download_progress(): liveupdater_download_progress

Byte-based progress of the current download session, with a per-resolution breakdown in the low/high fields (requires manifest with file_sizes).

Returns

  • liveupdater_download_progress

get_total_downloadable_progress(): number

Returns

  • number

is_module_in_queue(module_name: string): boolean | undefined

Parameters

  • module_name: string

Returns

  • boolean | undefined

focus(module_name: string, lane_or_low?: number | undefined, high_priority?: number | undefined)

Parameters

  • module_name: string
  • lane_or_low?: number | undefined — M.PRIORITY_IDS.*, or the low priority
  • high_priority?: number | undefined — required when lane_or_low is a number

request_module_load(module_name: string)

Parameters

  • module_name: string

get_module_status(module_name: string): { state: number; position: number | undefined; low: LuaTable; high: LuaTable }

Parameters

  • module_name: string

Returns

  • { state: number; position: number | undefined; low: LuaTable; high: LuaTable }

pin_module(module_name: string)

Parameters

  • module_name: string

is_high_upgrade_ready(module_name: string): boolean

Parameters

  • module_name: string

Returns

  • boolean

promote_module(module_name: string, cb: (ok: boolean) => void)

Call only after the collection proxy reading this module is unloaded.

Parameters

  • module_name: string
  • cb: (ok: boolean) => void

Variables

MSG_INITIALIZED: Hash

Posted to every listener once init finishes.

MSG_INITIALIZATION_FAILED: Hash

Message id reserved for a failed initialization; this version never posts it.

MSG_FILE_LOADED: Hash

Posted with file_name and module_name each time an archive is mounted.

MSG_MODULE_LOADED: Hash

Posted with file_name and module_name once every archive of a module is mounted.

MSG_ALL_LOADED: Hash

Posted once every queued archive is mounted.

MSG_NETWORK_ERROR: Hash

Posted when an archive download fails; the download retries after five seconds.

DEBUG: number

Debug log level passed to the set_log_function callback.

INFO: number

Info log level passed to the set_log_function callback.

WARN: number

Warning log level passed to the set_log_function callback.

ERROR: number

Error log level passed to the set_log_function callback.

FATAL: number

Fatal log level passed to the set_log_function callback.

RES_HIGH_ONLY: liveupdater_res_mode

res_mode that loads only the high-resolution archives; the default.

RES_LOW_ONLY: liveupdater_res_mode

res_mode that loads only the low-resolution archives.

RES_BOTH: liveupdater_res_mode

res_mode that loads both resolutions.

Types

liveupdater_module

liveupdater_module.files: string[]

liveupdater_module.priority: number

liveupdater_module.res_mode: liveupdater_res_mode | undefined

liveupdater_module.by_request: boolean | undefined

liveupdater_module.processed: boolean | undefined

liveupdater_module.focus_low: number | undefined

set by M.focus, overrides priority for the low resolution

liveupdater_module.focus_high: number | undefined

set by M.focus, overrides priority for the high resolution

liveupdater_file_version_info

liveupdater_file_version_info.version: string

liveupdater_file_version_info.size: number | undefined

liveupdater_manifest

liveupdater_manifest.version: string

liveupdater_manifest.deps: LuaTable<string, string[]>

liveupdater_manifest.file_versions: LuaTable<string, liveupdater_file_version_info | string>

liveupdater_manifest.file_sizes: LuaTable<string, number> | undefined

liveupdater_manifest.file_md5: LuaTable<string, string> | undefined

chunked md5 of each .arcd0; absent → no cache check

liveupdater_manifest.md5_chunk_size: number | undefined

chunk size of file_md5: hashmd5 of the concatenated hex md5 of each chunk

liveupdater_manifest.file_md5_size: LuaTable<string, number> | undefined

bytes covered by file_md5: the archive up to its dmanifest entry

liveupdater_manifest.merged_archives: LuaTable<string, string[]> | undefined

pack name -> member archive names

liveupdater_manifest_group

liveupdater_manifest_group.lowres: liveupdater_manifest | undefined

present only when the lowres resolution is active

liveupdater_manifest_group.highres: liveupdater_manifest | undefined

present only when the highres resolution is active

liveupdater_manifest_side

liveupdater_manifest_side.versions: LuaTable<string, string>

archive name -> version hash

liveupdater_manifest_side.sizes: LuaTable<string, number>

archive name -> archive size in bytes (0 if the manifest has no sizes)

liveupdater_manifest_side.md5: LuaTable<string, string>

archive name -> chunked md5 of .arcd0 (empty when manifest has no file_md5)

liveupdater_manifest_side.md5_chunk_size: number

liveupdater_manifest_side.md5_size: LuaTable<string, number>

archive name -> bytes covered by md5

liveupdater_manifest_side.merged_into: LuaTable<string, string>

member archive name -> pack name

liveupdater_manifest_side.pack_set: LuaTable<string, boolean>

set of pack archive names from merged_archives

liveupdater_manifest_side.dep_lists: LuaTable<string, string[]>

collection file -> dependency archive names

liveupdater_manifest_side.dep_set: LuaTable<string, boolean>

set of all dependency archive names

liveupdater_manifest_side.path: string

server path for this resolution

liveupdater_manifest_side.prefix: string

progress prefix for this resolution

liveupdater_manifest_cache

liveupdater_manifest_cache.low: liveupdater_manifest_side | undefined

liveupdater_manifest_cache.high: liveupdater_manifest_side | undefined

liveupdater_file_progress

liveupdater_file_progress.progress: number

liveupdater_file_progress.prefix: string

liveupdater_queue_item

liveupdater_queue_item.file_name: string

liveupdater_queue_item.priority: number

liveupdater_queue_item.version: string

liveupdater_queue_item.size: number

liveupdater_queue_item.module_name: string

liveupdater_queue_item.path: string

liveupdater_queue_item.prefix: string

liveupdater_queue_item.resolution: liveupdater_resolution

liveupdater_queue_item.remount: boolean | undefined

liveupdater_queue_item.order: number | undefined

liveupdater_queue_item.reason: string | undefined

liveupdater_queue_item.download_class: number | undefined

M.DOWNLOAD_CLASS.*, set when the item is queued

liveupdater_queue_item.verify_attempts: number | undefined

liveupdater_queue_item.mount_attempts: number | undefined

liveupdater_queue_item.retry_at: number | undefined

liveupdater_module_file_progress

liveupdater_module_file_progress.name: string

liveupdater_module_file_progress.progress: number

liveupdater_module_progress

liveupdater_module_progress.name: string

liveupdater_module_progress.progress: number

liveupdater_module_progress.files: liveupdater_module_file_progress[]

liveupdater_resolution_progress

liveupdater_resolution_progress.total_bytes: number

liveupdater_resolution_progress.downloaded_bytes: number

liveupdater_resolution_progress.pending_files: number

liveupdater_resolution_progress.progress: number

0..100, reaches 100 exactly when nothing is left to download

liveupdater_download_progress

liveupdater_download_progress.low: liveupdater_resolution_progress

liveupdater_download_progress.high: liveupdater_resolution_progress

liveupdater_download_progress.gate: liveupdater_resolution_progress

liveupdater_download_progress.downloading: liveupdater_active_download[]

liveupdater_active_download

liveupdater_active_download.key: string

liveupdater_active_download.size: number

liveupdater_active_download.bytes: number

liveupdater_active_download.in_gate: boolean

liveupdater_init_options

liveupdater_init_options.modules: LuaTable<string, liveupdater_module>

liveupdater_init_options.lowres_server_path: string | undefined

liveupdater_init_options.hires_server_path: string | undefined

liveupdater

liveupdater.initialized: boolean

liveupdater.saved_list: LuaTable<string, string>

liveupdater.save_cache_key: string

liveupdater.modules: LuaTable<string, liveupdater_module>

liveupdater_in_flight_state

liveupdater_in_flight_state.item: liveupdater_queue_item

liveupdater_in_flight_state.bytes: number

liveupdater_in_flight_state.phase: number

M.IN_FLIGHT_PHASE.*

liveupdater_mount_job

liveupdater_mount_job.load_info: liveupdater_queue_item

liveupdater_mount_job.dl_name: string | undefined

liveupdater_mount_job.size_ok: boolean | undefined

liveupdater_staged_high

liveupdater_staged_high.load_info: liveupdater_queue_item

liveupdater_staged_high.pending_name: string

liveupdater_staged_high.mounted: boolean

liveupdater_cache_md5_state

liveupdater_cache_md5_state.md5: string

liveupdater_cache_md5_state.ok: boolean | undefined

liveupdater_cache_md5_state.failed: boolean | undefined

liveupdater_cache_md5_state.retried: boolean | undefined

liveupdater_cache_check_entry

liveupdater_cache_check_entry.file_name: string

liveupdater_cache_check_entry.version: string

liveupdater_cache_check_entry.md5: string

liveupdater_cache_check_entry.chunk_size: number

liveupdater_cache_check_entry.size: number

On this page

Functionsset_log_function(fn: (level: number, message: string) => void)set_platform_supported(supported: boolean)set_save_cache_key(key: string)set_bench_log(enabled: boolean)bench_mark(event: string, details?: string | undefined)set_verify_hashes(enabled: boolean)set_parallel_downloads(count?: number | undefined)get_parallel_downloads(): numberset_post_budget(sec?: number | undefined)get_post_budget(): numberhas_module(module_name: string): booleanis_module_loaded(module_name: string): booleaninit(options: liveupdater_init_options, cb: (success: boolean, error_text: string | undefined) => void, module_available_fn?: ((module_name: string) => boolean) | undefined)add_listener(url?: Url | undefined)remove_listener(url?: Url | undefined)get_module_progress(module_name: string, module?: liveupdater_module | undefined): liveupdater_module_progress | undefinedis_liveupdate_loaded(): booleanget_downloadable_files(): LuaTable<string, liveupdater_file_progress>get_downloadable_missing_files(): LuaTable<string, string>get_modules_download_progress(module_names: string | string[]): liveupdater_download_progressget_download_progress(): liveupdater_download_progressget_total_downloadable_progress(): numberis_module_in_queue(module_name: string): boolean | undefinedfocus(module_name: string, lane_or_low?: number | undefined, high_priority?: number | undefined)request_module_load(module_name: string)get_module_status(module_name: string): { state: number; position: number | undefined; low: LuaTable; high: LuaTable }pin_module(module_name: string)is_high_upgrade_ready(module_name: string): booleanpromote_module(module_name: string, cb: (ok: boolean) => void)VariablesMSG_INITIALIZED: HashMSG_INITIALIZATION_FAILED: HashMSG_FILE_LOADED: HashMSG_MODULE_LOADED: HashMSG_ALL_LOADED: HashMSG_NETWORK_ERROR: HashDEBUG: numberINFO: numberWARN: numberERROR: numberFATAL: numberRES_HIGH_ONLY: liveupdater_res_modeRES_LOW_ONLY: liveupdater_res_modeRES_BOTH: liveupdater_res_modeTypesliveupdater_moduleliveupdater_module.files: string[]liveupdater_module.priority: numberliveupdater_module.res_mode: liveupdater_res_mode | undefinedliveupdater_module.by_request: boolean | undefinedliveupdater_module.processed: boolean | undefinedliveupdater_module.focus_low: number | undefinedliveupdater_module.focus_high: number | undefinedliveupdater_file_version_infoliveupdater_file_version_info.version: stringliveupdater_file_version_info.size: number | undefinedliveupdater_manifestliveupdater_manifest.version: stringliveupdater_manifest.deps: LuaTable<string, string[]>liveupdater_manifest.file_versions: LuaTable<string, liveupdater_file_version_info | string>liveupdater_manifest.file_sizes: LuaTable<string, number> | undefinedliveupdater_manifest.file_md5: LuaTable<string, string> | undefinedliveupdater_manifest.md5_chunk_size: number | undefinedliveupdater_manifest.file_md5_size: LuaTable<string, number> | undefinedliveupdater_manifest.merged_archives: LuaTable<string, string[]> | undefinedliveupdater_manifest_groupliveupdater_manifest_group.lowres: liveupdater_manifest | undefinedliveupdater_manifest_group.highres: liveupdater_manifest | undefinedliveupdater_manifest_sideliveupdater_manifest_side.versions: LuaTable<string, string>liveupdater_manifest_side.sizes: LuaTable<string, number>liveupdater_manifest_side.md5: LuaTable<string, string>liveupdater_manifest_side.md5_chunk_size: numberliveupdater_manifest_side.md5_size: LuaTable<string, number>liveupdater_manifest_side.merged_into: LuaTable<string, string>liveupdater_manifest_side.pack_set: LuaTable<string, boolean>liveupdater_manifest_side.dep_lists: LuaTable<string, string[]>liveupdater_manifest_side.dep_set: LuaTable<string, boolean>liveupdater_manifest_side.path: stringliveupdater_manifest_side.prefix: stringliveupdater_manifest_cacheliveupdater_manifest_cache.low: liveupdater_manifest_side | undefinedliveupdater_manifest_cache.high: liveupdater_manifest_side | undefinedliveupdater_file_progressliveupdater_file_progress.progress: numberliveupdater_file_progress.prefix: stringliveupdater_queue_itemliveupdater_queue_item.file_name: stringliveupdater_queue_item.priority: numberliveupdater_queue_item.version: stringliveupdater_queue_item.size: numberliveupdater_queue_item.module_name: stringliveupdater_queue_item.path: stringliveupdater_queue_item.prefix: stringliveupdater_queue_item.resolution: liveupdater_resolutionliveupdater_queue_item.remount: boolean | undefinedliveupdater_queue_item.order: number | undefinedliveupdater_queue_item.reason: string | undefinedliveupdater_queue_item.download_class: number | undefinedliveupdater_queue_item.verify_attempts: number | undefinedliveupdater_queue_item.mount_attempts: number | undefinedliveupdater_queue_item.retry_at: number | undefinedliveupdater_module_file_progressliveupdater_module_file_progress.name: stringliveupdater_module_file_progress.progress: numberliveupdater_module_progressliveupdater_module_progress.name: stringliveupdater_module_progress.progress: numberliveupdater_module_progress.files: liveupdater_module_file_progress[]liveupdater_resolution_progressliveupdater_resolution_progress.total_bytes: numberliveupdater_resolution_progress.downloaded_bytes: numberliveupdater_resolution_progress.pending_files: numberliveupdater_resolution_progress.progress: numberliveupdater_download_progressliveupdater_download_progress.low: liveupdater_resolution_progressliveupdater_download_progress.high: liveupdater_resolution_progressliveupdater_download_progress.gate: liveupdater_resolution_progressliveupdater_download_progress.downloading: liveupdater_active_download[]liveupdater_active_downloadliveupdater_active_download.key: stringliveupdater_active_download.size: numberliveupdater_active_download.bytes: numberliveupdater_active_download.in_gate: booleanliveupdater_init_optionsliveupdater_init_options.modules: LuaTable<string, liveupdater_module>liveupdater_init_options.lowres_server_path: string | undefinedliveupdater_init_options.hires_server_path: string | undefinedliveupdaterliveupdater.initialized: booleanliveupdater.saved_list: LuaTable<string, string>liveupdater.save_cache_key: stringliveupdater.modules: LuaTable<string, liveupdater_module>liveupdater_in_flight_stateliveupdater_in_flight_state.item: liveupdater_queue_itemliveupdater_in_flight_state.bytes: numberliveupdater_in_flight_state.phase: numberliveupdater_mount_jobliveupdater_mount_job.load_info: liveupdater_queue_itemliveupdater_mount_job.dl_name: string | undefinedliveupdater_mount_job.size_ok: boolean | undefinedliveupdater_staged_highliveupdater_staged_high.load_info: liveupdater_queue_itemliveupdater_staged_high.pending_name: stringliveupdater_staged_high.mounted: booleanliveupdater_cache_md5_stateliveupdater_cache_md5_state.md5: stringliveupdater_cache_md5_state.ok: boolean | undefinedliveupdater_cache_md5_state.failed: boolean | undefinedliveupdater_cache_md5_state.retried: boolean | undefinedliveupdater_cache_check_entryliveupdater_cache_check_entry.file_name: stringliveupdater_cache_check_entry.version: stringliveupdater_cache_check_entry.md5: stringliveupdater_cache_check_entry.chunk_size: numberliveupdater_cache_check_entry.size: number