|
| 1 | +#Upgrade guide from Cocos2d-JS v3.1 to Cocos2d-JS v3.2 |
| 2 | + |
| 3 | +## 0. Upgrade to Cocos2d-JS v3.1 |
| 4 | + |
| 5 | +If you are still using Cocos2d-html5 or previous version of Cocos2d-JS, you need to read the previous upgrade guide first : [Upgrade guide to Cocos2d-JS v3.1](../../v3.0rc0/upgrade-guide/en.md) |
| 6 | + |
| 7 | +## 1. Reduce package size with modulirization in JSB |
| 8 | + |
| 9 | +In Cocos2d-JS v3.2, during compilation, Cocos2d-x modules and related JavaScript Bindings code can be automatically excluded from the final package if they are not used. As you may already know, our web engine support modularization with `modules` section in project.json file. However, this configuration doesn't take effect in JSB, you should do the following to exclude any module you don't need in JSB. |
| 10 | + |
| 11 | +In AppDelegate.cpp, you will find `applicationDidFinishLaunching` function in which all JSB bindings are registered. If the registration code for a module is commented out, then the base Cocos2d-x module won't be used, during linking the linker will exclude it. This is a common optimization in linker, so it will take effect for both Android and iOS apps. Of course, all modules that you don't register their bindings won't be available in your JavaScript code. |
| 12 | + |
| 13 | +At last, you only need to compile your project. The minimum size of Android package in Cocos2d-JS v3.2 is 4.4mb. |
| 14 | + |
| 15 | +``` |
| 16 | +bool AppDelegate::applicationDidFinishLaunching() |
| 17 | +{ |
| 18 | + // initialize director |
| 19 | + auto director = Director::getInstance(); |
| 20 | + auto glview = director->getOpenGLView(); |
| 21 | + if(!glview) { |
| 22 | + glview = cocos2d::GLViewImpl::createWithRect("Release3_2", Rect(0,0,900,640)); |
| 23 | + director->setOpenGLView(glview); |
| 24 | + } |
| 25 | +
|
| 26 | + // set FPS. the default value is 1.0/60 if you don't call this |
| 27 | + director->setAnimationInterval(1.0 / 60); |
| 28 | + |
| 29 | + ScriptingCore* sc = ScriptingCore::getInstance(); |
| 30 | + sc->addRegisterCallback(register_all_cocos2dx); |
| 31 | + sc->addRegisterCallback(register_cocos2dx_js_core); |
| 32 | + sc->addRegisterCallback(register_cocos2dx_js_extensions); |
| 33 | + sc->addRegisterCallback(jsb_register_system); |
| 34 | +
|
| 35 | + // extension can be commented out to reduce the package |
| 36 | + sc->addRegisterCallback(register_all_cocos2dx_extension); |
| 37 | + sc->addRegisterCallback(register_all_cocos2dx_extension_manual); |
| 38 | +
|
| 39 | + // chipmunk can be commented out to reduce the package |
| 40 | + sc->addRegisterCallback(jsb_register_chipmunk); |
| 41 | + // opengl can be commented out to reduce the package |
| 42 | + sc->addRegisterCallback(JSB_register_opengl); |
| 43 | + |
| 44 | + // builder can be commented out to reduce the package |
| 45 | + sc->addRegisterCallback(register_all_cocos2dx_builder); |
| 46 | + sc->addRegisterCallback(register_CCBuilderReader); |
| 47 | + |
| 48 | + // ui can be commented out to reduce the package, attension studio need ui module |
| 49 | + sc->addRegisterCallback(register_all_cocos2dx_ui); |
| 50 | + sc->addRegisterCallback(register_all_cocos2dx_ui_manual); |
| 51 | +
|
| 52 | + // studio can be commented out to reduce the package, |
| 53 | + sc->addRegisterCallback(register_all_cocos2dx_studio); |
| 54 | + sc->addRegisterCallback(register_all_cocos2dx_studio_manual); |
| 55 | + |
| 56 | + // spine can be commented out to reduce the package |
| 57 | + sc->addRegisterCallback(register_all_cocos2dx_spine); |
| 58 | + sc->addRegisterCallback(register_all_cocos2dx_spine_manual); |
| 59 | + |
| 60 | + // XmlHttpRequest can be commented out to reduce the package |
| 61 | + sc->addRegisterCallback(MinXmlHttpRequest::_js_register); |
| 62 | + // websocket can be commented out to reduce the package |
| 63 | + sc->addRegisterCallback(register_jsb_websocket); |
| 64 | + // sokcet io can be commented out to reduce the package |
| 65 | + sc->addRegisterCallback(register_jsb_socketio); |
| 66 | + |
| 67 | +#if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID) |
| 68 | + sc->addRegisterCallback(JavascriptJavaBridge::_js_register); |
| 69 | +#elif (CC_TARGET_PLATFORM == CC_PLATFORM_IOS || CC_TARGET_PLATFORM == CC_PLATFORM_MAC) |
| 70 | + sc->addRegisterCallback(JavaScriptObjCBridge::_js_register); |
| 71 | +#endif |
| 72 | + sc->start(); |
| 73 | + sc->runScript("script/jsb_boot.js"); |
| 74 | + ScriptEngineProtocol *engine = ScriptingCore::getInstance(); |
| 75 | + ScriptEngineManager::getInstance()->setScriptEngine(engine); |
| 76 | + ScriptingCore::getInstance()->runScript("main.js"); |
| 77 | +
|
| 78 | + return true; |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +## 2. Restart game and hot update related APIs |
| 83 | + |
| 84 | +Since Cocos2d-JS v3.0 Beta, we have provided AssetsManager for assets and scripts hot update ability. Ever since, its stability is greatly improved and become reliable. Thank to our developers, we have also collected many great suggestions and feature requests. In v3.2, we decided to add two importants ones: |
| 85 | + |
| 86 | +1. Clean a script's cache |
| 87 | + |
| 88 | + A script will be cached in JSB, so even if you updated it with AssetsManager, it won't take effect even if you require it again. In this case, we provided `cleanScript` API to clean its cache. |
| 89 | + |
| 90 | + ``` |
| 91 | + cc.sys.cleanScript(scriptPath); |
| 92 | + ``` |
| 93 | +
|
| 94 | +2. Restart game |
| 95 | +
|
| 96 | + Very often, when the hot update is done, the game need to be restarted entirely. So we provided restart game API, it will do the following steps: |
| 97 | +
|
| 98 | + 1. Clean up Cocos2d-x's environment |
| 99 | + 2. Restart the JavaScript VM |
| 100 | + 3. Register all script bindings |
| 101 | + 4. Re-execute the main.js |
| 102 | +
|
| 103 | + The API is |
| 104 | +
|
| 105 | + ``` |
| 106 | + cc.game.restart() |
| 107 | + ``` |
| 108 | + |
| 109 | +3. Manifest's new API: getSearchPaths |
| 110 | +
|
| 111 | + If you want the new JavaScript files updated via AssetsManager to take effect, there are two requirements to be satisfied: |
| 112 | + |
| 113 | + 1. JavaScript files must be updated correctly. |
| 114 | + 2. Everytime before the game start up, the search paths for the new scripts must be prepended before the execution of `cc.game.run()`. Then in `cc.game.run`, the engine will load the updated scripts. |
| 115 | + |
| 116 | + This means the search paths of the updated assets must be stored locally, so we have provided a new API of Manifest to retrieve the search pahts. Then the local storage can be used to save the search paths, it's our recommended way, but developers can also use whatever they want to save the paths persistantly. Here is an recommended process after the scripts hot update via AssetsManager: |
| 117 | + |
| 118 | + ``` |
| 119 | + // After update succeeded, updated manifest will become the new local manifest. |
| 120 | + var searchPaths = assetsManager.getLocalManifest().getSearchPaths(); |
| 121 | + // The search paths can be coded to JSON string then stored in cc.sys.localStorage, so that it can be retrieved and preppended to jsb.fileUtils during the game restart. |
| 122 | + cc.sys.localStorage.setItem("AssetsSearchPaths", JSON.stringify(searchPaths)); |
| 123 | + // Restart the game to let new scripts take effect. |
| 124 | + cc.game.restart(); |
| 125 | + ``` |
| 126 | +
|
| 127 | +Hope these new APIs will make hot update in your game much eaiser. |
0 commit comments