@wukong-kit/hot-update

Wukong Kit hot-update runtime for Cocos Creator 3.x native builds.

This library wraps jsb.AssetsManager and provides:

• install/uninstall through the Wukong editor panel
• ordered runtime initialization through WKLibBootstrap
• optional default update panel
• update state/progress events
• persisted search paths after an update finishes
• optional automatic check, automatic update, and automatic restart

Important

Hot update only works on native platforms. In the editor, browser preview, and other non-native runtimes, the manager reports unsupported and does not run update logic.

The library is disabled by default. Installing it will not start downloads until you pass enabled: true and a valid localManifestUrl.

When Wukong initializes installed libraries, initWukongHotUpdate() automatically tries to read:

assets/resources/wukong-libs/hot-update/config/hot-update.json

So a project can enable hot update by editing that config, without changing WKLibBootstrap.

Basic Usage

import { hotUpdateManager, initWukongHotUpdate } from '@wukong-kit/hot-update';

await initWukongHotUpdate({
  enabled: true,
  localManifestUrl: manifestAsset.nativeUrl,
  autoCheck: true,
  autoUpdate: false,
  showDefaultPanel: true,
});

hotUpdateManager.on((event) => {
  console.log(event.state, event.message, event.progress.filesProgress);
});

// Call this after receiving `new-version-found`, or enable `autoUpdate`.
hotUpdateManager.update();

localManifestUrl should point to the local project.manifest bundled with the native package. In Cocos Creator, the usual pattern is to expose a manifest asset on your bootstrap script and pass manifestAsset.nativeUrl.

Search Paths

When an update finishes, the manager reads the manifest search paths, prepends them to jsb.fileUtils, and stores them in sys.localStorage.

If you need to apply search paths earlier in a custom boot script, call:

import { applyWukongHotUpdateSearchPaths } from '@wukong-kit/hot-update';

applyWukongHotUpdateSearchPaths();

Options

interface WKHotUpdateInitOptions {
  enabled?: boolean;
  localManifestUrl?: string;
  storagePath?: string;
  autoCheck?: boolean;
  autoUpdate?: boolean;
  showDefaultPanel?: boolean;
  panelTitle?: string;
  restartAfterFinished?: boolean;
  searchPathStorageKey?: string;
  verifyCallback?: (path: string, asset: WKHotUpdateAssetInfo) => boolean;
}

The installed asset template includes a starter config at:

assets/resources/wukong-libs/hot-update/config/hot-update.json