石心
返回「计算机、信息技术与工程」

cocos2dx

从 Cocos2d x v3.16 入手

计算机、信息技术与工程 知识笔记 作者 Perrin Yong 约 12 分钟
更多
Markdown 结构化数据
本文目录 20 个章节

从 Cocos2d-x v3.16 入手

cocos2dx

0 · 版本与生态定位

维度 说明
核心版本 v3.16（2017-09）——3.x 系列最后一个长期维护版本，新功能已停止；4.x 转向 C++17 单渲染后端，Creator 3.x 转 TypeScript + Vulkan/OpenGL ES3。
语言层 C++ 引擎内核 + JSB / Lua 绑定。官方脚手架 cocos new 支持 -l cpp / js / lua 三种模板。
推荐场景 对 Creator 3.x 资源/编辑器依赖较小，且希望 一套逻辑同时跑原生和浏览器 时，3.16 仍是成熟方案。

1 · 引擎整体框架

            ┌──────────── JS / Lua 脚本层 ─────────┐
            │     (业务逻辑、UI、状态机 …)          │
            └─────▲─────────┬───────────▲─────────┘
                  │JSB/Lua  │            │ 网络/文件/音频 Adapter
        (SpiderMonkey v33)  │            │  (不同平台各自实现)
                  │         │            │
┌─────────────────┴─────────┴────────────┴────────────────────┐
│               Cocos2d-x C++ 核心（场景树·渲染·动画…）        │
└─────────────────▲─────────┬────────────▲────────────────────┘
                  │平台抽象 │            │OpenGL ES / WebGL / Metal
                  │         │
          安卓 / iOS / Win / macOS         浏览器 / 小游戏

关键词：

关键模块 作用 / 关注点
Director / Scene / Node 对应 对象树 与生命周期（Director::runWithScene ↔ update）。
Renderer 3.16 仍是 OpenGL ES2 管线；3D 模块早期版。
JSB (JavaScript Binding) 自动生成的 C++ ↔ JS 桥，把 cc.Sprite 等暴露给脚本。
Platform / Utils 文件、线程、网络、多媒体差异化封装。
Build 脚本 Python2 + scons + Ant/Eclipse/Android-Studio；HTML5 侧用 Google Closure 打包。

2 · 通用开发环境

工具/SDK Windows macOS / Linux
Python 2.7.x（cocos_console） 同左
JDK 8+ 8+
Android NDK r14b - r16b（适配 3.16 preset） 同左
Android Studio 3.x（Gradle 2.x-3.x） 同左
Visual Studio 2015 / 2017 (MSBuild) ——
Xcode —— 8–10
Node.js 8+（本地服务器 / wx 工具） 同左
微信 DevTools — —

环境变量：NDK_ROOT、ANDROID_SDK_ROOT、ANT_ROOT、JAVA_HOME、PATH 把 python、cocos.bat/cocos 放进去。

3 · 项目生命周期

3.1 创建

## JS 模板，项目名 MyGame
cocos new MyGame -l js -p com.demo.mygame -d D:/Games

目录要点：

MyGame/
├─ frameworks/
│  ├─ cocos2d-x/         ← C++ 引擎源码 + JSB
│  └─ cocos2d-html5/     ← 纯 JS 引擎
├─ proj.android/         ← Ant/Eclipse 旧模板
├─ proj.android-studio/  ← Android Studio Gradle
├─ proj.win32/           ← VS2015 sln
├─ proj.ios_mac/         ← Xcode
└─ res/ src/ main.js     ← 资源 & 脚本入口

3.2 调试

平台 命令 默认行为
Win32 cocos run -p win32 VS 工程 → Debug → bin/win32/MyGame.exe
Android cocos run -p android --android-studio 调用 gradlew installDebug
Web cocos run -p web 启动 Python SimpleHTTPServer http://localhost:8000/

3.3 构建（Release）

目标 命令 产物
Android APK cocos compile -p android --android-studio -m release proj.android-studio/app/build/outputs/apk/release/
iOS IPA cocos compile -p ios -m release Xcode CLI archive
Windows EXE cocos compile -p win32 -m release bin/win32/MyGame.exe
WebGL cocos compile -p web -m release publish/html5/ (index.html, game.min.js)

4 · Android 专项

  1. Gradle 升级约束 3.16 模板用 com.android.tools.build:gradle:2.2.3；要升更高版本须同时更新 NDK 配置 (externalNativeBuild.ndkBuild)。
  2. ABI 修改 Application.mk：APP_ABI := armeabi-v7a arm64-v8a；x86 如需模拟器测试再加。
  3. 签名与对齐 proj.android-studio/gradle.properties→ MYAPP_RELEASE_STORE_FILE；或手动在 .gradle 中配置 signingConfigs release { ... }。
  4. 混淆 Proguard Cocos 自带 -dontobfuscate；若接 SDK 需添加 keep class com.xxx.** { *; }.

6 · 常见问题速查

症状 原因 & 修复
控制台中文乱码 cocos … --ol en 或 chcp 65001 & set PYTHONIOENCODING=utf-8
Android libcocos2dx.so 过大 APP_STL := c++_static 换 c++_shared；ndk-build NDK_DEBUG=0
WebGL 黑屏 / 无法加载资源 路径大小写、project.json 列表遗漏、服务器 MIME（特别是 .mp3, .json）
微信小游戏报 “require is not defined” adapter 未复制 / game.js 加载顺序错误
JS 调用原生崩溃栈不好看 开启 --source-map；Android 用 ndk-stack + breakpad；Web 端利用 source-map-support 折叠行号

7 · 学习路线图（建议用时 & 里程碑）

  1. 1-2 天·快速上手

    • 跑通 cocos new / run、改 Logo、换一张贴图。

  2. 3-5 天·核心 API 探索

    • Node/Action/Scheduler、输入系统、音频、物理 (Chipmunk/Box2D)。

  3. 1 周·跨平台构建

    • Android Studio & Win32 Release；理解 Android.mk, Application.mk。

  4. 1-2 周·WebGL & 微信小游戏适配

    • 拆包体、CDN、远端热更新；Adapter 调试。

  5. 随项目·源码阅读

    • Director & Renderer 代码；JSB 自动绑定脚本生成。

配套资料 《Cocos2d-x Game Development By Example》《Cocos 官方论坛 3.x 板块》《cocos2d-x 源码注释（国内翻译）》

C++, js, lua 关系

引擎层

frameworks/
├─ cocos2d-html5/        ← 纯 JavaScript 引擎（浏览器 / Web 环境跑）
└─ cocos2d-x/            ← C++ 引擎源码 + JSB 桥（iOS / Android / Win / macOS 跑）
目录 作用 构建目标
cocos2d-html5 • 全 JS 实现的渲染 & 场景树• 直接依赖 WebGL / Canvas API -p web、微信小游戏、QQ 小游戏、Facebook Instant …
cocos2d-x • C++ 引擎核心• JSB（JavaScript → C++) 桥把你的脚本嵌入原生 App -p android win32 ios mac 等

HTML5 引擎 只需要浏览器即可工作； C++ 引擎 负责所有 原生平台，并在内部嵌一个 JavaScript 解释器（SpiderMonkey v33）。

                 +--------------------+
                 |  Your Script (JS)  |
                 +---------▲----------+
                           |
        +------------------| JSB Bridge (C++) |
        |                  v                  |
+-------+---------+   +-----------+   +---------------+
| cocos2d-html5   |   | cocos2d-x |   | LuaBinding    |
|  (WebGL Only)   |   | (C++)     |   | (tolua++)     |
+-----------------+   +-----------+   +---------------+
              |<------共享渲染/节点系统/资源加载------>|

绑定层

WebGL应用

UI编辑

脚本编写

浏览器应用

cocos2d-html5

环境: Python 2.7、Java JDK 7+（Google Closure Compiler 用）、Git

新建项目

cocos new MyGame -l js -d D:\Games -p com.demo.mygame
  • -l js 生成纯 JS 工程

调试运行

cocos run -p web

http://localhost:8000/

发布 Release

cocos compile -p web -m release --source-map
  • Closure Compiler → game.min.js + app.min.js（源码合并）。
  • 资源管理：res/ 按 project.json 列表加载；可自行改写成远端 CDN。

运行 使用 Python 内置服务器

python -m http.server 8000  # 启动服务器，端口 8000

使用Node.js的 http-server.

npm install -g http-server
http-server -p 8000  # 启动服务器，端口 8000

微信小游戏

cocos2d-html5 + WeChat adapter

适配层只是把浏览器调用（DOM、XMLHttpRequest、Audio）重定向到 wx.*，再做包体分包/资源远程加载。

社区适配包 https://github.com/cocos-creator-packages/weapp-adapter https://forum.cocos.org/t/cocos2d-html5-3-16/55119

  1. 覆盖引擎 将 adapter 内的 cocos2d-html5 & WeChatGame 复制到项目 frameworks/ 下。
  2. 构建 cocos compile -p web -m release
  3. 拷贝适配层 WeChatGame/ → publish/html5/
  4. 微信 DevTools 导入
    • 目录指向 publish/html5
    • AppID / 域名白名单
    • 勾选 ES6 to ES5、上传代码时自动压缩。

包体 ≤ 8 MB 主包：可启用 subpackages + CDN 远程资源

4 MB：把 project.json 与 res/ 挪到远端 CDN → 在 game.js 里改 window.REMOTE_SERVER_ROOT='https://cdn.xxx.com/game'

UI功能编写

方案 适用性 导出格式 WebGL / 小游戏能否直接用？ 简要步骤
① Cocos Studio 2.3.3（官方停更） 3.16 原生匹配 JSON 或 CSB(Timeline 动画 .animation) JSON 可以；CSB 仅原生 1. 安装 Studio2. 新建 _UI/Scene_3. Publish Settings 里勾 Export JSON4. ui/MainScene.json 拷到 res/5. JS 端：jsvar res = ccs.load("res/MainScene.json");this.addChild(res.node);
② Cocos Creator 1.10-2.x 如果你愿意用 Creator 画 UI、逻辑仍写 3.16 JS 自带 .fire 场景可 插件导出 JSON 需社区插件；微信 OK 1. 安装旧版 Creator2. 菜单 → 发布 → Cocos2d-JS 3.x 插件（GitHub）3. 生成 creator_scene.json + 贴图4. 直接 ccs.load() 同上。
③ 纯代码 (ccui) 最轻量，无外部工具 — 100% 通用 1. JS 里 new ccui.Button()、ccui.Layout() 拼 UI2. 通过 JSON 自己存配置或热更新。 
src/
├─ app.js          ← 程序入口（MainScene 切换、全局事件）
├─ scenes/
│   ├─ MainScene.js
│   └─ GameScene.js
├─ ui/
│   └─ PauseLayer.js
└─ util/
    └─ Net.js
main.js            ← 引擎默认入口（别改名字）

Cocos2d-x 构建的一些坑

可手动添加 .cocos-project.json

{
    "engine_version": "cocos2d-x-3.17.2",
    "has_native": true,
    "project_type": "js"
}

NDK, CMake等环境配置要匹配

@REM set NDK_ROOT=D:/Env/AndroidEnv/SDK/ndk/android-ndk-r16b
set NDK_ROOT=D:/Env/AndroidEnv/SDK/ndk/21.4.7075529
set PATH=%PATH%;D:/Env/AndroidEnv/SDK/cmake/3.10.2.4988404/bin
cocos compile -p android --android-studio -m release