{ "schemaVersion": "0.11.0", "canonical": "https://www.pystone.net/notes/cocos2dx-overview/", "atlas": "https://www.pystone.net/?node=cocos2dx-overview#knowledge-atlas", "markdown": "https://www.pystone.net/notes/cocos2dx-overview.md", "context": "https://www.pystone.net/notes/cocos2dx-overview.context.json", "knowledgeVersion": "224c990773de.5fa8af6e39fa", "build": { "siteCommit": "224c990773de166d23a886306577dd90379529ce", "notesCommit": "5fa8af6e39fa3891d1b9b4832bfa6c4e0ecaaf0a", "builtAt": "1970-01-01T00:00:00.000Z", "version": "224c990773de.5fa8af6e39fa" }, "id": "note:cocos2dx-overview", "slug": "cocos2dx-overview", "title": "cocos2dx", "type": "note", "visibility": "public", "idStability": "rename-stable", "author": { "name": "Perrin Yong", "profile": "https://www.pystone.net/profile/" }, "publisher": { "name": "Perrin Yong", "profile": "https://www.pystone.net/profile/" }, "aliases": [], "summary": "从 Cocos2d x v3.16 入手", "contentRole": "unspecified", "isMoc": false, "mocRecognition": "none", "generated": false, "attribution": "unspecified", "domain": "10-计算机、信息技术与工程", "tags": [], "mocs": [], "contentHash": "b441a63757e4f6d8278103109eb7cd9b2da3c2a77742b54d3a0b7aff19a72bc0", "assets": [], "headings": [ { "depth": 1, "text": "cocos2dx", "anchor": "cocos2dx", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#cocos2dx" }, { "depth": 2, "text": "0 · 版本与生态定位", "anchor": "0-版本与生态定位", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#0-%E7%89%88%E6%9C%AC%E4%B8%8E%E7%94%9F%E6%80%81%E5%AE%9A%E4%BD%8D" }, { "depth": 2, "text": "1 · 引擎整体框架", "anchor": "1-引擎整体框架", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#1-%E5%BC%95%E6%93%8E%E6%95%B4%E4%BD%93%E6%A1%86%E6%9E%B6" }, { "depth": 2, "text": "2 · 通用开发环境", "anchor": "2-通用开发环境", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#2-%E9%80%9A%E7%94%A8%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83" }, { "depth": 2, "text": "3 · 项目生命周期", "anchor": "3-项目生命周期", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#3-%E9%A1%B9%E7%9B%AE%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F" }, { "depth": 3, "text": "3.1 创建", "anchor": "31-创建", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#31-%E5%88%9B%E5%BB%BA" }, { "depth": 3, "text": "3.2 调试", "anchor": "32-调试", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#32-%E8%B0%83%E8%AF%95" }, { "depth": 3, "text": "3.3 构建（Release）", "anchor": "33-构建release", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#33-%E6%9E%84%E5%BB%BArelease" }, { "depth": 2, "text": "4 · Android 专项", "anchor": "4-android-专项", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#4-android-%E4%B8%93%E9%A1%B9" }, { "depth": 2, "text": "6 · 常见问题速查", "anchor": "6-常见问题速查", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#6-%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E9%80%9F%E6%9F%A5" }, { "depth": 2, "text": "7 · 学习路线图（建议用时 & 里程碑）", "anchor": "7-学习路线图建议用时-里程碑", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#7-%E5%AD%A6%E4%B9%A0%E8%B7%AF%E7%BA%BF%E5%9B%BE%E5%BB%BA%E8%AE%AE%E7%94%A8%E6%97%B6-%E9%87%8C%E7%A8%8B%E7%A2%91" }, { "depth": 2, "text": "C++, js, lua 关系", "anchor": "c-js-lua-关系", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#c-js-lua-%E5%85%B3%E7%B3%BB" }, { "depth": 2, "text": "引擎层", "anchor": "引擎层", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#%E5%BC%95%E6%93%8E%E5%B1%82" }, { "depth": 2, "text": "绑定层", "anchor": "绑定层", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#%E7%BB%91%E5%AE%9A%E5%B1%82" }, { "depth": 2, "text": "WebGL应用", "anchor": "webgl应用", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#webgl%E5%BA%94%E7%94%A8" }, { "depth": 2, "text": "UI编辑", "anchor": "ui编辑", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#ui%E7%BC%96%E8%BE%91" }, { "depth": 2, "text": "脚本编写", "anchor": "脚本编写", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#%E8%84%9A%E6%9C%AC%E7%BC%96%E5%86%99" }, { "depth": 2, "text": "浏览器应用", "anchor": "浏览器应用", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#%E6%B5%8F%E8%A7%88%E5%99%A8%E5%BA%94%E7%94%A8" }, { "depth": 2, "text": "微信小游戏", "anchor": "微信小游戏", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#%E5%BE%AE%E4%BF%A1%E5%B0%8F%E6%B8%B8%E6%88%8F" }, { "depth": 2, "text": "UI功能编写", "anchor": "ui功能编写", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#ui%E5%8A%9F%E8%83%BD%E7%BC%96%E5%86%99" }, { "depth": 2, "text": "Cocos2d-x 构建的一些坑", "anchor": "cocos2d-x-构建的一些坑", "citation": "https://www.pystone.net/notes/cocos2dx-overview/#cocos2d-x-%E6%9E%84%E5%BB%BA%E7%9A%84%E4%B8%80%E4%BA%9B%E5%9D%91" } ], "claims": [], "outgoing": [], "incoming": [ { "id": "note:game-graphics-and-runtime", "title": "游戏图形与运行时", "url": "https://www.pystone.net/notes/game-graphics-and-runtime/", "atlas": "https://www.pystone.net/?node=game-graphics-and-runtime#knowledge-atlas", "label": "游戏图形与运行时", "origin": "explicit", "humanReviewed": true, "context": "Cocos中的“cocos2dx”导航项", "citation": "https://www.pystone.net/notes/game-graphics-and-runtime/#cocos" } ], "contentMarkdown": "从 **Cocos2d-x v3.16** 入手\n\n# cocos2dx\n## 0 · 版本与生态定位\n\n| 维度 | 说明 |\n| -------- | -------------------------------------------------------------------------------------------------------- |\n| **核心版本** | v3.16（2017-09）——3.x 系列最后一个长期维护版本，新功能已停止；4.x 转向 C++17 单渲染后端，Creator 3.x 转 TypeScript + Vulkan/OpenGL ES3。 |\n| **语言层** | **C++ 引擎内核** + JSB / Lua 绑定。官方脚手架 `cocos new` 支持 `-l cpp / js / lua` 三种模板。 |\n| **推荐场景** | 对 Creator 3.x 资源/编辑器依赖较小，且希望 **一套逻辑同时跑原生和浏览器** 时，3.16 仍是成熟方案。 |\n\n---\n\n## 1 · 引擎整体框架\n\n```text\n ┌──────────── JS / Lua 脚本层 ─────────┐\n │ (业务逻辑、UI、状态机 …) │\n └─────▲─────────┬───────────▲─────────┘\n │JSB/Lua │ │ 网络/文件/音频 Adapter\n (SpiderMonkey v33) │ │ (不同平台各自实现)\n │ │ │\n┌─────────────────┴─────────┴────────────┴────────────────────┐\n│ Cocos2d-x C++ 核心（场景树·渲染·动画…） │\n└─────────────────▲─────────┬────────────▲────────────────────┘\n │平台抽象 │ │OpenGL ES / WebGL / Metal\n │ │\n 安卓 / iOS / Win / macOS 浏览器 / 小游戏\n```\n\n**关键词：**\n\n| 关键模块 | 作用 / 关注点 |\n| ---------------------------- | ---------------------------------------------------------------------------- |\n| **Director / Scene / Node** | 对应 **对象树** 与生命周期（`Director::runWithScene` ↔ `update`）。 |\n| **Renderer** | 3.16 仍是 **OpenGL ES2** 管线；3D 模块早期版。 |\n| **JSB (JavaScript Binding)** | 自动生成的 C++ ↔ JS 桥，把 `cc.Sprite` 等暴露给脚本。 |\n| **Platform / Utils** | 文件、线程、网络、多媒体差异化封装。 |\n| **Build 脚本** | Python2 + scons + Ant/Eclipse/Android-Studio；HTML5 侧用 **Google Closure** 打包。 |\n\n---\n\n## 2 · 通用开发环境\n\n| 工具/SDK | Windows | macOS / Linux |\n| ------------------ | --------------------------- | ------------- |\n| **Python** | 2.7.x（`cocos_console`） | 同左 |\n| **JDK** | 8+ | 8+ |\n| **Android NDK** | r14b - r16b（适配 3.16 preset） | 同左 |\n| **Android Studio** | 3.x（Gradle 2.x-3.x） | 同左 |\n| **Visual Studio** | 2015 / 2017 (MSBuild) | —— |\n| **Xcode** | —— | 8–10 |\n| **Node.js** | 8+（本地服务器 / wx 工具） | 同左 |\n| **微信 DevTools** | — | — |\n\n> **环境变量**：`NDK_ROOT`、`ANDROID_SDK_ROOT`、`ANT_ROOT`、`JAVA_HOME`、`PATH` 把 `python`、`cocos.bat`/`cocos` 放进去。\n\n---\n\n## 3 · 项目生命周期\n\n### 3.1 创建\n\n```bash\n## JS 模板，项目名 MyGame\ncocos new MyGame -l js -p com.demo.mygame -d D:/Games\n```\n\n目录要点：\n\n```text\nMyGame/\n├─ frameworks/\n│ ├─ cocos2d-x/ ← C++ 引擎源码 + JSB\n│ └─ cocos2d-html5/ ← 纯 JS 引擎\n├─ proj.android/ ← Ant/Eclipse 旧模板\n├─ proj.android-studio/ ← Android Studio Gradle\n├─ proj.win32/ ← VS2015 sln\n├─ proj.ios_mac/ ← Xcode\n└─ res/ src/ main.js ← 资源 & 脚本入口\n```\n\n### 3.2 调试\n\n| 平台 | 命令 | 默认行为 |\n| ----------- | --------------------------------------- | --------------------------------------------------- |\n| **Win32** | `cocos run -p win32` | VS 工程 → Debug → `bin/win32/MyGame.exe` |\n| **Android** | `cocos run -p android --android-studio` | 调用 `gradlew installDebug` |\n| **Web** | `cocos run -p web` | 启动 Python SimpleHTTPServer `http://localhost:8000/` |\n\n### 3.3 构建（Release）\n\n| 目标 | 命令 | 产物 |\n| --------------- | ------------------------------------------------------ | ---------------------------------------------------- |\n| **Android APK** | `cocos compile -p android --android-studio -m release` | `proj.android-studio/app/build/outputs/apk/release/` |\n| **iOS IPA** | `cocos compile -p ios -m release` | Xcode CLI archive |\n| **Windows EXE** | `cocos compile -p win32 -m release` | `bin/win32/MyGame.exe` |\n| **WebGL** | `cocos compile -p web -m release` | `publish/html5/` (`index.html`, `game.min.js`) |\n\n---\n\n## 4 · Android 专项\n\n1. **Gradle 升级约束**\n *3.16 模板用 `com.android.tools.build:gradle:2.2.3`*；要升更高版本须同时更新 NDK 配置 (`externalNativeBuild.ndkBuild`)。\n2. **ABI**\n 修改 `Application.mk`：`APP_ABI := armeabi-v7a arm64-v8a`；x86 如需模拟器测试再加。\n3. **签名与对齐**\n `proj.android-studio/gradle.properties`→ `MYAPP_RELEASE_STORE_FILE`；或手动在 `.gradle` 中配置 `signingConfigs release { ... }`。\n4. **混淆 Proguard**\n Cocos 自带 `-dontobfuscate`；若接 SDK 需添加 `keep class com.xxx.** { *; }`.\n\n---\n\n## 6 · 常见问题速查\n\n| 症状 | 原因 & 修复 |\n| --------------------------------- | ---------------------------------------------------------------------------------- |\n| 控制台中文乱码 | `cocos … --ol en` 或 `chcp 65001 & set PYTHONIOENCODING=utf-8` |\n| Android `libcocos2dx.so` 过大 | `APP_STL := c++_static` 换 `c++_shared`；`ndk-build NDK_DEBUG=0` |\n| WebGL 黑屏 / 无法加载资源 | 路径大小写、`project.json` 列表遗漏、服务器 MIME（特别是 `.mp3`, `.json`） |\n| 微信小游戏报 *“require is not defined”* | adapter 未复制 / `game.js` 加载顺序错误 |\n| JS 调用原生崩溃栈不好看 | 开启 `--source-map`；Android 用 `ndk-stack` + breakpad；Web 端利用 source-map-support 折叠行号 |\n\n## 7 · 学习路线图（建议用时 & 里程碑）\n\n1. **1-2 天·快速上手**\n\n * 跑通 `cocos new / run`、改 Logo、换一张贴图。\n2. **3-5 天·核心 API 探索**\n\n * Node/Action/Scheduler、输入系统、音频、物理 (Chipmunk/Box2D)。\n3. **1 周·跨平台构建**\n\n * Android Studio & Win32 Release；理解 `Android.mk`, `Application.mk`。\n4. **1-2 周·WebGL & 微信小游戏适配**\n\n * 拆包体、CDN、远端热更新；Adapter 调试。\n5. **随项目·源码阅读**\n\n * Director & Renderer 代码；JSB 自动绑定脚本生成。\n\n> **配套资料**\n> *《Cocos2d-x Game Development By Example》《Cocos 官方论坛 3.x 板块》《cocos2d-x 源码注释（国内翻译）》*\n\n\n## C++, js, lua 关系\n\n## 引擎层\n\n```mathematica\nframeworks/\n├─ cocos2d-html5/ ← 纯 JavaScript 引擎（浏览器 / Web 环境跑）\n└─ cocos2d-x/ ← C++ 引擎源码 + JSB 桥（iOS / Android / Win / macOS 跑）\n```\n\n| 目录 | 作用 | 构建目标 |\n| ------------------- | ------------------------------------------------------ | ---------------------------------------- |\n| **`cocos2d-html5`** | • 全 JS 实现的渲染 & 场景树• 直接依赖 WebGL / Canvas API | `-p web`、微信小游戏、QQ 小游戏、Facebook Instant … |\n| **`cocos2d-x`** | • C++ 引擎核心• *JSB*（JavaScript → C++) 桥把你的脚本嵌入原生 App | `-p android` `win32` `ios` `mac` 等 |\n\n_HTML5 引擎_ 只需要浏览器即可工作；\n_C++ 引擎_ 负责所有 **原生平台**，并在内部嵌一个 JavaScript 解释器（SpiderMonkey v33）。\n\n```sql\n +--------------------+\n | Your Script (JS) |\n +---------▲----------+\n |\n +------------------| JSB Bridge (C++) |\n | v |\n+-------+---------+ +-----------+ +---------------+\n| cocos2d-html5 | | cocos2d-x | | LuaBinding |\n| (WebGL Only) | | (C++) | | (tolua++) |\n+-----------------+ +-----------+ +---------------+\n |<------共享渲染/节点系统/资源加载------>|\n\n```\n\n## 绑定层\n\n## WebGL应用\n\n## UI编辑\n\n\n## 脚本编写\n\n\n## 浏览器应用\n\ncocos2d-html5\n\n**环境**: Python 2.7、Java JDK 7+（Google Closure Compiler 用）、Git\n\n新建项目\n```shell\ncocos new MyGame -l js -d D:\\Games -p com.demo.mygame\n```\n* `-l js` 生成纯 JS 工程\n\n调试运行\n```text\ncocos run -p web\n```\n`http://localhost:8000/`\n\n发布 Release\n```bash\ncocos compile -p web -m release --source-map\n```\n\n* Closure Compiler → `game.min.js` + `app.min.js`（源码合并）。\n* 资源管理：`res/` 按 `project.json` 列表加载；可自行改写成远端 CDN。\n\n运行\n**使用 Python 内置服务器**\n```bash\npython -m http.server 8000 # 启动服务器，端口 8000\n```\n\n使用Node.js的 `http-server`.\n```bash\nnpm install -g http-server\nhttp-server -p 8000 # 启动服务器，端口 8000\n```\n\n## 微信小游戏\n\ncocos2d-html5 + WeChat adapter\n\n适配层只是把浏览器调用（DOM、XMLHttpRequest、Audio）重定向到 `wx.*`，再做包体分包/资源远程加载。\n\n> **社区适配包**\n> https://github.com/cocos-creator-packages/weapp-adapter\n> https://forum.cocos.org/t/cocos2d-html5-3-16/55119\n\n1. **覆盖引擎**\n 将 adapter 内的 `cocos2d-html5` & `WeChatGame` 复制到项目 `frameworks/` 下。\n2. **构建** `cocos compile -p web -m release`\n3. **拷贝适配层** `WeChatGame/` → `publish/html5/`\n4. **微信 DevTools 导入**\n * 目录指向 `publish/html5`\n * AppID / 域名白名单\n * 勾选 `ES6 to ES5`、`上传代码时自动压缩`。\n\n**包体 ≤ 8 MB** 主包：可启用 `subpackages` + CDN 远程资源\n> 4 MB：把 `project.json` 与 `res/` 挪到远端 CDN → 在 `game.js` 里改 `window.REMOTE_SERVER_ROOT='https://cdn.xxx.com/game'`\n\n## UI功能编写\n| 方案 | 适用性 | 导出格式 | WebGL / 小游戏能否直接用？ | 简要步骤 |\n| ------------------------------ | ---------------------------------- | ---------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **① 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);` |\n| **② 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()` 同上。 |\n| **③ 纯代码 (ccui)** | 最轻量，无外部工具 | — | 100% 通用 | 1. JS 里 `new ccui.Button()`、`ccui.Layout()` 拼 UI2. 通过 JSON 自己存配置或热更新。 |\n\n```js\nsrc/\n├─ app.js ← 程序入口（MainScene 切换、全局事件）\n├─ scenes/\n│ ├─ MainScene.js\n│ └─ GameScene.js\n├─ ui/\n│ └─ PauseLayer.js\n└─ util/\n └─ Net.js\nmain.js ← 引擎默认入口（别改名字）\n\n```\n\n\n## Cocos2d-x 构建的一些坑\n\n\n可手动添加 .cocos-project.json\n```json\n{\n \"engine_version\": \"cocos2d-x-3.17.2\",\n \"has_native\": true,\n \"project_type\": \"js\"\n}\n```\n\nNDK, CMake等环境配置要匹配\n```cpp\n@REM set NDK_ROOT=D:/Env/AndroidEnv/SDK/ndk/android-ndk-r16b\nset NDK_ROOT=D:/Env/AndroidEnv/SDK/ndk/21.4.7075529\nset PATH=%PATH%;D:/Env/AndroidEnv/SDK/cmake/3.10.2.4988404/bin\ncocos compile -p android --android-studio -m release\n```\n" }