---
title: "cocos2dx"
author: "Perrin Yong"
author_profile: https://www.pystone.net/profile/
published_by: "Perrin Yong"
canonical: https://www.pystone.net/notes/cocos2dx-overview/
type: note
content_role: unspecified
visibility: public
id_stability: rename-stable
source_path: "10-计算机、信息技术与工程/05-游戏图形与运行时/Cocos/cocos2dx.md"
content_hash: b441a63757e4f6d8278103109eb7cd9b2da3c2a77742b54d3a0b7aff19a72bc0
knowledge_version: 224c990773de.5fa8af6e39fa
site_commit: 224c990773de166d23a886306577dd90379529ce
notes_commit: 5fa8af6e39fa3891d1b9b4832bfa6c4e0ecaaf0a
---
从 **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 · 引擎整体框架

```text
            ┌──────────── 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 创建

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

目录要点：

```text
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 关系

## 引擎层

```mathematica
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）。

```sql
                 +--------------------+
                 |  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

新建项目
```shell
cocos new MyGame -l js -d D:\Games -p com.demo.mygame
```
* `-l js` 生成纯 JS 工程

调试运行
```text
cocos run -p web
```
`http://localhost:8000/`

发布 Release
```bash
cocos compile -p web -m release --source-map
```

* Closure Compiler → `game.min.js` + `app.min.js`（源码合并）。
* 资源管理：`res/` 按 `project.json` 列表加载；可自行改写成远端 CDN。

运行
**使用 Python 内置服务器**
```bash
python -m http.server 8000  # 启动服务器，端口 8000
```

使用Node.js的 `http-server`.
```bash
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 JSON`4. `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 自己存配置或热更新。                                                                                                                       |

```js
src/
├─ app.js          ← 程序入口（MainScene 切换、全局事件）
├─ scenes/
│   ├─ MainScene.js
│   └─ GameScene.js
├─ ui/
│   └─ PauseLayer.js
└─ util/
    └─ Net.js
main.js            ← 引擎默认入口（别改名字）

```


## Cocos2d-x 构建的一些坑


可手动添加 .cocos-project.json
```json
{
    "engine_version": "cocos2d-x-3.17.2",
    "has_native": true,
    "project_type": "js"
}
```

NDK, CMake等环境配置要匹配
```cpp
@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
```