Nanfeng

Notes on software development, code, and curious ideas

Secure Hot Updates for Cocos2d-x Lua Games

In
Version manifests, asset downloads, verification, search paths, recovery, and deployment safety for Cocos2d-x hot updates.

Cocos2d-x AssetsManagerEx can update Lua scripts and game assets without replacing the application binary. A typical deployment publishes version.manifest, project.manifest, and the referenced files on a versioned server path.

The version manifest identifies the current package and project manifest URL. The project manifest lists every managed asset, its size, and a digest. At startup, the client compares local and remote versions, downloads changed assets into writable storage, verifies them, and updates search paths.

Event-driven update flow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
local storage = cc.FileUtils:getInstance():getWritablePath() .. "hot-update/"
local manager = cc.AssetsManagerEx:create("project.manifest", storage)
manager:retain()

local listener = cc.EventListenerAssetsManagerEx:create(manager, function(event)
    local code = event:getEventCode()
    if code == cc.EventAssetsManagerEx.EventCode.UPDATE_PROGRESSION then
        print("progress", event:getPercentByFile())
    elseif code == cc.EventAssetsManagerEx.EventCode.UPDATE_FINISHED then
        print("update complete")
    elseif code == cc.EventAssetsManagerEx.EventCode.ERROR_UPDATING then
        print("asset failed", event:getAssetId(), event:getMessage())
    end
end)

cc.Director:getInstance():getEventDispatcher()
    :addEventListenerWithFixedPriority(listener, 1)
manager:update()

The exact event names and bindings depend on the engine version. Release the retained manager and remove the listener when the owner is destroyed.

Manifest generation

A build script should walk the packaged asset root, calculate a deterministic digest and size for each relative path, and write stable JSON. Normalize path separators, exclude temporary files and the generated manifest itself, and generate manifests from an immutable release directory.

Security and recovery

A digest detects corruption but does not prove who published a file. Serve updates over HTTPS and authenticate the manifest with a digital signature anchored in the application. Validate all paths to prevent traversal, limit download sizes, and do not execute partially verified Lua code.

Download into a staging version, verify the complete set, then switch atomically. Keep a known-good manifest and search-path state so a crash or bad release can roll back. Test interrupted downloads, low storage, server errors, corrupted assets, downgrade attempts, and app-version compatibility before enabling hot updates in production.

+