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- Pick a release from HGPoint/defold_live_unbundler releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as live_unbundler from "live_unbundler"
- Pick a release from HGPoint/defold_live_unbundler releases and add its Source code (zip) URL (or a packaged
Functions
set_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)
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:stringdetails?: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_optionscb:(success: boolean, error_text: string | undefined) => voidmodule_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:stringmodule?: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:stringlane_or_low?:number | undefined— M.PRIORITY_IDS.*, or the low priorityhigh_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:stringcb:(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.*