【cocos2d-js官方文檔】二、資源管理員Assets Manager

標籤：

這篇文檔將介紹Cocos2d-JS 3.0的一個重量級新特性：資源管理員（僅支援JSB）。資源管理員是為遊戲運行時的資源熱更新而設計的，這裡的資源可以是圖片，音頻甚至遊戲指令碼本身。使用資源管理員，你將可以上傳新的資源到你的伺服器，你的遊戲會跟蹤遠程伺服器上的修改，將新的資源下載到使用者的裝置上並在遊戲中使用新的資源。就這樣，全新的設計，新的遊玩體驗甚至全新的遊戲內容都將立刻被推送到你的使用者手上。重要的是，你不需要針對各個渠道去重新打包你的應用並經曆痛苦的應用程式更新審核，這個過程沒有任何成本！

使用情境

想象一下你的遊戲已經發布在市集中，但是你突然發現一個設計上的疏漏或者一些非常負面的使用者反饋，你肯定心急如焚，但是修改完成之後，還是不得不等待無數渠道的軟體打包以及惱人的市集審核...直到通過審核上線，還需要使用者去更新自己的軟體版本，或者...審核也許通不過。看到這裡，有如此經驗的人心情一定不會好，我想說，這樣的過程實在是太痛苦了，而且很多使用者可能在這個過程中早已流失。

其他使用情境：

• 情人節快到了，你想要組織一個遊戲內活動，錯過時機肯定是你最不想要看到的結果。
• 當你發現一個嚴重的bug。
• 當你想要添加一些新的情境或者關卡來延長遊戲的生命。
• 以及非常多其他的情況...

對於以上這些情況，如果你可以在開發完成後快速得部署到使用者手上，我說的快速，是也許一個晚上，這難道不是很吸引人嗎？資源管理員就是為了這些情況而設計的。

特性

Cocos2d-JS v3.0 RC0版中的資源管理員新增了非常多強大的功能特性，使得熱更新的過程更加快捷方便。

• 多線程並行下載支援
• 兩層進度統計資訊：檔案級以及位元組級
• Zip壓縮檔支援
• 斷點續傳
• 詳細的錯誤報表
• 檔案下載失敗重試支援

資源管理員的使用

實際上，使用資源管理員的使用相當簡單，首先，你的應用程式套件中將需要一個JSON格式的初始的設定檔(manifest)。

在這個設定檔中，你需要提供伺服器上的對應設定檔地址，當前資源版本和一組資源描述，然後你就可以在遊戲代碼中使用jsb.AssetsManager的API來檢查或更新對應資源的最新版本。

設定檔

下面是設定檔的一個簡單樣本：

{    "packageUrl" : "http://example.com/assets_manager/TestScene/",    "remoteVersionUrl" : "http://example.com/assets_manager/TestScene/version.manifest",    "remoteManifestUrl" : "http://example.com/assets_manager/TestScene/project.manifest",    "version" : "1.0.0",    "engineVersion" : "Cocos2d-JS v3.0 RC0",    "assets" : {        "Images/background.jpg" : {            "md5" : "..."        },        "Images/icon.png" : {            "md5" : "..."        },        "Images/button.png" : {            "md5" : "..."        },        "src/game.js" : {            "md5" : "..."        },        "src/layer.js" : {            "md5" : "..."        },        "compressed.zip" : {            "md5" : "...",            "compressed" : true        }    },    "searchPaths" : [        "res/"    ]}

• packageUrl : 遠端資源的下載根路徑。
• remoteVersionUrl : 遠程版本檔案的路徑，用來判斷伺服器端是否有新版本的資源。
• remoteManifestUrl : 遠程設定檔的路徑，包含版本資訊以及所有資源資訊。
• version : 設定檔對應的版本。
• engineVersion : 設定檔對應的引擎版本。
• assets : 所有資源資訊。
  • key : 鍵代表資源的相對路徑（相對於packageUrl）。
  • md5 : md5值代表資源檔的版本資訊。
  • compressed : [可選項] 如果值為true，檔案被下載後會自動被解壓，目前僅支援zip壓縮格式。
• searchPaths : 需要添加到cocos2d引擎中的搜尋路徑列表。

版本檔案version.manifest檔案應該包含與設定檔完全相同的前五項資訊。這個檔案是可選的，如果它未被找到或成功失敗，資源管理員會自動下載完整的設定檔。但是當設定檔包含很多資源非常龐大的時候，版本檔案將極大縮短版本比較的時間。

使用jsb.AssetsManager

下面是jsb.AssetsManager使用的範例程式碼：

var manager = new jsb.AssetsManager(manifestUrl, storagePath);manager.update();// 由於下載過程是非同步，你需要增加manager的索引數以保證它不會被Cocos2d-x的記憶體管理釋放掉manager.retain();if (!manager.getLocalManifest().isLoaded()) {    cc.log("Fail to update assets, step skipped.");}else {    var listener = new cc.EventListenerAssetsManager(manager, function(event) {        switch (event.getEventCode())        {            case cc.EventAssetsManager.ERROR_NO_LOCAL_MANIFEST:                cc.log("No local manifest file found, skip assets update.");                break;            case cc.EventAssetsManager.UPDATE_PROGRESSION:                var percent = event.getPercent();                var filePercent = event.getPercentByFile();                cc.log("Download percent : " + percent + " | File percent : " + filePercent);                break;            case cc.EventAssetsManager.ERROR_DOWNLOAD_MANIFEST:            case cc.EventAssetsManager.ERROR_PARSE_MANIFEST:                cc.log("Fail to download manifest file, update skipped.");                break;            case cc.EventAssetsManager.ALREADY_UP_TO_DATE:            case cc.EventAssetsManager.UPDATE_FINISHED:                cc.log("Update finished.");                // 由於增加了manager的引用計數，你需要在合適的時候將它釋放掉，並確保這個對象不再被使用到                manager.release();                break;            case cc.EventAssetsManager.UPDATE_FAILED:                cc.log("Update failed. " + event.getMessage());                // 直接重新下載失敗的資源，建議你對重試次數計數，超過一定次數放棄                manager.downloadFailedAssets();                break;            case cc.EventAssetsManager.ERROR_UPDATING:                cc.log("Asset update error: " + event.getAssetId() + ", " + event.getMessage());                break;            case cc.EventAssetsManager.ERROR_DECOMPRESS:                cc.log(event.getMessage());                break;            default:                break;        }    }}

你也可以參考js-tests中的Extensions/AssetsManagerTest測試例。其他jsb.AssetsManager的API如下：

• checkUpdate()
• getState()
• getStoragePath()
• getLocalManifest()
• getRemoteManifest()

已知bug

資源管理員可能會在windows和iOS模擬器上遇到無法建立並下載檔案的問題，我們會儘快解決這個問題，與此同時，請使用iOS真機進行調試。

【cocos2d-js官方文檔】二、資源管理員Assets Manager