playbooks

home / skills / partme-ai / full-stack-skills / cocos2d-x

cocos2d-x skill

/skills/cocos2d-x

This skill guides you through Cocos2d-x v4 game development, covering nodes, scenes, physics, rendering, and multi-platform deployment.

npx playbooks add skill partme-ai/full-stack-skills --skill cocos2d-x

Review the files below or copy the command above to add this skill to your agents.

Files (14)
SKILL.md
7.0 KB
---
name: cocos2d-x
description: Provides comprehensive guidance for Cocos2d-x v4 game engine including scene graph, nodes, sprites, actions, animations, physics, rendering, shaders, and platform deployment. Use when the user asks about Cocos2d-x, needs to create games, implement game features, set up development environments, or deploy games to multiple platforms.
license: Complete terms in LICENSE.txt
---

## When to use this skill

Use this skill whenever the user wants to:
- Create Cocos2d-x v4 games or applications
- Learn Cocos2d-x v4 core concepts (Node, Sprite, Scene, Action)
- Set up Cocos2d-x v4 development environment
- Work with sprites, textures, animations, and labels
- Implement scene management and node lifecycle
- Handle input events (touch, mouse, keyboard)
- Use physics engine (Box2D) and collision detection
- Implement rendering pipeline, shaders, and particle systems
- Build and deploy games for multiple platforms (Windows, macOS, Linux, Android, iOS)
- Use CMake build system and command-line tools
- Migrate from older Cocos2d-x versions
- Extend engine with custom rendering and script bindings

## How to use this skill

To work with Cocos2d-x v4:

1. **Identify the topic** from the user's request:
   - Engine overview/了解引擎 → `examples/getting-started/about-engine.md`
   - Quick start/快速上手 → `examples/getting-started/quick-start.md`
   - Installation/安装配置 → `examples/getting-started/installation.md`
   - Node and Scene/节点和场景 → `examples/core/node-scene.md`
   - Sprite/精灵 → `examples/core/sprite.md`
   - Texture/纹理 → `examples/core/texture.md`
   - Animation/动画 → `examples/core/animation.md`
   - Action/动作 → `examples/core/action.md`
   - Label/标签 → `examples/core/label.md`
   - Scene management/场景管理 → `examples/core/scene.md`
   - Input handling/输入处理 → `examples/core/input.md`
   - Event system/事件系统 → `examples/core/event.md`
   - Physics/物理引擎 → `examples/advanced/physics.md`
   - Rendering/渲染 → `examples/advanced/rendering.md`
   - Shaders/着色器 → `examples/advanced/shader.md`
   - Particle system/粒子系统 → `examples/advanced/particle.md`
   - Build system/构建系统 → `examples/tools/build-system.md`
   - Platform deployment/平台部署 → `examples/tools/deployment.md`

2. **Load the appropriate example file** from the `examples/` directory:
   - `examples/getting-started/about-engine.md` - Engine overview and features
   - `examples/getting-started/quick-start.md` - Create first project
   - `examples/getting-started/installation.md` - Environment setup
   - `examples/core/node-scene.md` - Node and Scene concepts
   - `examples/core/sprite.md` - Sprite creation and manipulation
   - `examples/core/texture.md` - Texture loading and management
   - `examples/core/animation.md` - Animation system
   - `examples/core/action.md` - Action system and sequences
   - `examples/core/label.md` - Label and text rendering
   - `examples/core/scene.md` - Scene management and transitions
   - `examples/core/input.md` - Touch, mouse, and keyboard input
   - `examples/core/event.md` - Event system and listeners
   - `examples/advanced/physics.md` - Physics engine integration
   - `examples/advanced/rendering.md` - Rendering pipeline
   - `examples/advanced/shader.md` - Custom shaders
   - `examples/advanced/particle.md` - Particle effects
   - `examples/tools/build-system.md` - CMake and build configuration
   - `examples/tools/deployment.md` - Platform-specific deployment

3. **Follow the specific instructions** in that example file for syntax, structure, and best practices

   Each example file contains:
   - **Instructions**: Overview and usage guidelines
   - **Syntax**: API syntax and parameters
   - **Examples**: Complete code examples with explanations
   - **Reference**: Links to official documentation

4. **Generate C++ code** following Cocos2d-x v4 conventions:
   - Use `USING_NS_CC;` for namespace
   - Use `CREATE_FUNC()` macro for create functions
   - Follow Cocos2d-x naming conventions
   - Include proper error handling
   - Use smart pointers where appropriate

5. **Reference the official documentation**:
   - Official manual: https://docs.cocos.com/cocos2d-x/v4/manual/zh/
   - API reference: Check `api/` directory for detailed API documentation
   - Examples: Check `examples/` directory for code examples

6. **Use templates** when creating new projects:
   - `templates/project-structure.md` - Standard project structure
   - `templates/cmake-config.md` - CMake configuration examples


### Doc mapping (one-to-one with official documentation)

- See examples and API files → https://docs.cocos.com/cocos2d-x/v4/manual/zh/

## Core Concepts

### Node System
- **Node**: Base class for all display objects
- **Scene**: Root node of the scene graph
- **Sprite**: Image display node
- **Label**: Text display node
- **Node hierarchy**: Parent-child relationships

### Coordinate System
- Origin at bottom-left (OpenGL style)
- Anchor point for positioning
- Local and world coordinates

### Action System
- **Action**: Base class for node transformations
- **Sequence**: Chain multiple actions
- **Spawn**: Run actions simultaneously
- **Repeat**: Repeat actions multiple times
- **Ease**: Apply easing functions

### Scene Management
- Scene transitions
- Scene lifecycle (onEnter, onExit)
- Director for scene management

### Input Handling
- Touch events (single and multi-touch)
- Mouse events
- Keyboard events
- Event dispatcher system

## Platform Support

Cocos2d-x v4 supports:
- **Desktop**: Windows, macOS, Linux
- **Mobile**: Android, iOS
- **Web**: (via Cocos Creator)

## Build System

- **CMake**: Primary build system
- **Command-line tools**: `cocos` command
- **IDE support**: Visual Studio, Xcode, Android Studio

## Migration Guide

For migrating from older versions:
- Check `examples/migration/` for migration guides
- API changes and compatibility notes
- CMake migration from older build systems

## Reference Resources

- **Official Documentation**: https://docs.cocos.com/cocos2d-x/v4/manual/zh/
- **API Reference**: See `api/` directory
- **Examples**: See `examples/` directory
- **Templates**: See `templates/` directory

## Keywords

cocos2d-x, cocos2d, game engine, game development, C++ game, 2D game, cross-platform game, sprite, scene, node, action, animation, physics, rendering, shader, particle system, CMake, game framework, 游戏引擎, 游戏开发, 精灵, 场景, 节点, 动作, 动画, 物理引擎, 渲染, 着色器, 粒子系统

## Important Notes

1. **Version**: This skill covers Cocos2d-x v4 specifically
2. **Language**: C++ is the primary development language
3. **Build System**: CMake is required for building projects
4. **Platform**: Ensure platform-specific dependencies are installed
5. **Examples**: All code examples use C++ syntax
6. **Memory Management**: Cocos2d-x uses reference counting, be careful with retain/release cycles
7. **Coordinate System**: Uses OpenGL-style coordinates (origin at bottom-left)
8. **Thread Safety**: Most Cocos2d-x operations must be performed on the main thread

Overview

This skill provides practical, hands-on guidance for building games with Cocos2d-x v4. It covers core engine concepts, scene graph management, sprites, actions, physics, rendering, shaders, and cross-platform deployment. Use it to set up projects, implement features, and follow conventions for C++ development with CMake.

How this skill works

The skill maps user requests to focused topics (getting started, nodes, sprites, physics, rendering, deployment) and provides targeted example files and templates. It recommends specific example documents, C++ idioms, and CMake templates, then supplies code patterns, lifecycle advice, and migration notes. It emphasizes main-thread rules, memory management, and platform-specific build steps for Android, iOS, Windows, macOS, and Linux.

When to use it

  • Creating a new Cocos2d-x v4 game or prototype
  • Learning core engine concepts: Node, Scene, Sprite, Action
  • Setting up or troubleshooting the development environment and CMake builds
  • Implementing animations, physics integration, or custom shaders
  • Preparing platform-specific deployment for Android, iOS, desktop
  • Migrating projects from older Cocos2d-x versions

Best practices

  • Follow Cocos2d-x naming conventions and use USING_NS_CC for brevity
  • Use CREATE_FUNC() and follow reference-counting patterns; avoid retain/release cycles
  • Perform rendering and scene updates on the main thread only
  • Structure projects with provided templates and keep CMake configs clean and reproducible
  • Test input and physics on target devices early to catch platform differences
  • Modularize features: separate rendering, physics, and gameplay logic for easier debugging

Example use cases

  • Create a main scene with layered sprites, labels, and input handlers
  • Implement a physics-driven gameplay loop using Box2D or built-in physics
  • Animate sprites using Action sequences, Spawn, and easing functions
  • Write a custom fragment shader for a post-processing effect and integrate it into the rendering pipeline
  • Set up a cross-platform CMake project, build for Android and iOS, and produce signed artifacts
  • Migrate an older Cocos2d-x project to v4 and update deprecated APIs

FAQ

Which language is primary for Cocos2d-x v4 development?

C++ is the primary language; bindings may exist but core samples and engine extensions use C++.

Do I need CMake to build projects?

Yes. CMake is the recommended and supported build system for v4; templates and examples assume CMake.

Where should most engine operations run?

Most operations that touch nodes, rendering, or the scene graph must run on the main thread to ensure thread safety.