Cocos2d-x v4 官方文档学习总结

> **学习时间**: 2026 年 3 月 14 日

> **文档来源**: https://docs.cocos.com/cocos2d-x/v4/manual/zh/

> **文档版本**: Cocos2d-x v4 用户手册 Q3 2019 R.1

一、文档目录结构

📚 完整章节

| 章节 | 子章节 |

|------|--------|

| **一、新手入门** | v4 升级指南、范例、API 变更、迁移指南 |

| **二、了解引擎** | 引擎优势、学习资源、获取帮助、参与开发 |

| **三、基本概念** | 导演、场景、精灵、动作、序列、节点关系、日志 |

| **四、基本功能** | 精灵、动作、场景、UI 组件 |

| **五、进阶内容** | 特殊节点、事件分发、3D 支持、脚本、物理引擎、音频、高级话题 |

| **六、环境与工具** | 环境搭建、引擎工具、常见问题 |

二、核心概念详解

2.1 Director (导演)

**概念**：导演就像电影导演一样，控制着游戏的方方面面。

**职责**：

控制游戏流程
管理场景切换
处理游戏循环
协调各个组件

**v4 API 变更**：

```cpp

// ❌ 已废弃

CC_DEPRECATED_ATTRIBUTE static Director* sharedDirector();

void setDepthTest(bool on);

// ✅ 新方式

Director::getInstance();

Director::getInstance()->getRenderer()->setDepthTest(true);

```

2.2 Scene (场景)

**概念**：Scene 是一个容器，包含游戏所需的 Sprites、Labels、Nodes 和其他对象。

**特点**：

场景是游戏的独立单元
每个场景包含完整的游戏逻辑
可以包含多个子节点

**场景图 (Scene Graph)**：

```

Scene (场景)

└── Layer (层)

├── Sprite (精灵)

├── Node (节点)

│ └── Sprite (精灵)

└── UI (界面)

```

2.3 Sprite (精灵)

**概念**：Sprite 是一个 2D 图像，可以通过改变其属性来进行动画或变换。

**用途**：

游戏角色
敌人
道具
背景元素

**创建方法**：

```cpp

// 从图片创建

auto sprite = Sprite::create("player.png");

// 从精灵帧缓存创建

auto sprite = Sprite::createWithSpriteFrameName("player_01.png");

// 从纹理创建

auto texture = Director::getInstance()->getTextureCache()->addImage("texture.png");

auto sprite = Sprite::createWithTexture(texture);

```

2.4 Node (节点)

**核心特性**：

**变换**: 位置、旋转、缩放
**锚点**: 定位参考点 (Anchor Point)
**Z 顺序**: 渲染层级
**子节点**: 树形层级关系
**标签/名称**: 节点标识
**动作支持**: 执行 Action
**事件处理**: 触摸、键盘等

**节点关系**：

```cpp

// 添加子节点

parent->addChild(child);

parent->addChild(child, zOrder);

parent->addChild(child, zOrder, tag);

// 获取子节点

auto child = parent->getChildByTag(tag);

auto child = parent->getChildByName("name");

// 移除节点

node->removeFromParent();

parent->removeChild(child);

parent->removeAllChildren();

```

2.5 Action (动作)

**动作类型**：

| 类型 | 说明 | 示例 |

|------|------|------|

| **即时动作** | 立即完成 | `Show`, `Hide`, `FlipX`, `FlipY` |

| **间隔动作** | 持续一段时间 | `MoveTo`, `RotateBy`, `ScaleTo` |

| **缓动动作** | 带缓动效果 | `EaseIn`, `EaseOut`, `EaseElastic` |

| **复合动作** | 组合其他动作 | `Sequence`, `Spawn`, `Repeat` |

**基本动作示例**：

```cpp

// 移动

auto moveTo = MoveTo::create(2.0f, Vec2(100, 100));

auto moveBy = MoveBy::create(2.0f, Vec2(50, 50));

// 旋转

auto rotateTo = RotateTo::create(2.0f, 90.0f);

auto rotateBy = RotateBy::create(2.0f, 45.0f);

// 缩放

auto scaleTo = ScaleTo::create(2.0f, 2.0f);

auto scaleBy = ScaleBy::create(2.0f, 0.5f);

// 透明度

auto fadeIn = FadeIn::create(1.0f);

auto fadeOut = FadeOut::create(1.0f);

// 变色

auto tintTo = TintTo::create(2.0f, 255, 0, 0);

auto tintBy = TintBy::create(2.0f, -50, -50, -50);

```

2.6 Sequence (序列动作)

**概念 **：多个 `Action` 对象按**指定顺序依次执行**。

**示例**：

```cpp

auto mySprite = Node::create();

auto moveTo1 = MoveTo::create(2, Vec2(50,10));

auto moveBy1 = MoveBy::create(2, Vec2(100,10));

auto moveTo2 = MoveTo::create(2, Vec2(150,10));

auto delay = DelayTime::create(1);

// 按顺序执行：moveTo1 → delay → moveBy1 → delay.clone() → moveTo2

mySprite->runAction(Sequence::create(moveTo1, delay, moveBy1, delay.clone(),

moveTo2, nullptr));

```

**执行流程**：

```

moveTo1 (2s) → delay (1s) → moveBy1 (2s) → delay (1s) → moveTo2 (2s)

```

2.7 Spawn (并行动作)

**概念 **：多个 `Action` 对象**同时执行**。

**示例**：

```cpp

auto myNode = Node::create();

auto moveTo1 = MoveTo::create(2, Vec2(50,10));

auto moveBy1 = MoveBy::create(2, Vec2(100,10));

auto moveTo2 = MoveTo::create(2, Vec2(150,10));

// 同时执行所有动作

myNode->runAction(Spawn::create(moveTo1, moveBy1, moveTo2, nullptr));

```

**执行流程**：

```

moveTo1 (2s) ──┐

moveBy1 (2s) ──┼── 同时开始，独立执行

moveTo2 (2s) ──┘

```

2.8 动作最佳实践

**动作复用**: 使用 `clone()` 方法复用动作对象
**终止符**: `create()` 方法必须以 `nullptr` 结尾
**组合使用**: 可以在 Sequence 中嵌套 Spawn，或在 Spawn 中嵌套 Sequence
**反向执行**: Sequence 支持 `reverse()` 方法反向执行
**时间规划**: Spawn 中各动作独立计时，需考虑协调

三、事件分发机制

3.1 五种监听器类型

| 监听器类型 | 用途 |

|-----------|------|

| `EventListenerTouchOneByOne` | 单点触摸，逐个处理 |

| `EventListenerTouchAllAtOnce` | 多点触摸，一次性处理所有触摸点 |

| `EventListenerKeyboard` | 键盘输入事件 |

| `EventListenerMouse` | 鼠标事件（移动、滚动、按键） |

| `EventListenerCustom` | 自定义事件监听 |

3.2 事件优先级系统

**数值越小，优先级越高**
优先级为负数的监听器会先于正数优先级被触发
相同优先级的监听器按注册顺序触发

```cpp

auto listener = EventListenerTouchOneByOne::create();

listener->setPriority(1); // 数字越小优先级越高

```

3.3 触摸事件示例

```cpp

auto touchListener = EventListenerTouchOneByOne::create();

touchListener->onTouchBegan = [](Touch* touch, Event* event) {

CCLOG("Touch began at: %f, %f", touch->getLocation().x, touch->getLocation().y);

return true; // 返回 true 表示继续处理触摸

};

touchListener->onTouchMoved = [](Touch* touch, Event* event) {

CCLOG("Touch moved");

};

touchListener->onTouchEnded = [](Touch* touch, Event* event) {

CCLOG("Touch ended");

};

_eventDispatcher->addEventListenerWithSceneGraphPriority(touchListener, this);

```

3.4 键盘事件示例

```cpp

auto keyboardListener = EventListenerKeyboard::create();

keyboardListener->onKeyPressed = [](EventKeyboard::KeyCode keyCode, Event* event) {

CCLOG("Key pressed: %d", keyCode);

};

keyboardListener->onKeyReleased = [](EventKeyboard::KeyCode keyCode, Event* event) {

CCLOG("Key released: %d", keyCode);

};

_eventDispatcher->addEventListenerWithSceneGraphPriority(keyboardListener, this);

```

3.5 自定义事件示例

```cpp

// 创建自定义事件监听器

auto customListener = EventListenerCustom::create("my_custom_event",