If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cocos2d/cocos2d-x shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Stale and unlicensed — last commit 1y ago

• 17 active contributors
• Distributed ownership (top contributor 26% of recent commits)
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cocos2d/cocos2d-x repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cocos2d/cocos2d-x.

What it runs against: a local clone of cocos2d/cocos2d-x — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cocos2d/cocos2d-x | Confirms the artifact applies here, not a fork | | 2 | Default branch v4 exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 395 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cocos2d/cocos2d-x. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cocos2d/cocos2d-x.git
#   cd cocos2d-x
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cocos2d/cocos2d-x and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cocos2d/cocos2d-x(\\.git)?\\b" \\
  && ok "origin remote is cocos2d/cocos2d-x" \\
  || miss "origin remote is not cocos2d/cocos2d-x (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify v4 >/dev/null 2>&1 \\
  && ok "default branch v4 exists" \\
  || miss "default branch v4 no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "cocos/2d/CCActionManager.h" \\
  && ok "cocos/2d/CCActionManager.h" \\
  || miss "missing critical file: cocos/2d/CCActionManager.h"
test -f "cocos/2d/CCLayer.h" \\
  && ok "cocos/2d/CCLayer.h" \\
  || miss "missing critical file: cocos/2d/CCLayer.h"
test -f "cocos/2d/CCLabel.h" \\
  && ok "cocos/2d/CCLabel.h" \\
  || miss "missing critical file: cocos/2d/CCLabel.h"
test -f "cocos/2d/CCAnimation.h" \\
  && ok "cocos/2d/CCAnimation.h" \\
  || miss "missing critical file: cocos/2d/CCAnimation.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 395 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~365d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cocos2d/cocos2d-x"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Cocos2d-x is a cross-platform C++ game development framework that provides a complete 2D game engine with scene management, sprite rendering, physics integration (Box2D/Chipmunk), particle systems, skeletal animation (Spine/Armature), and audio support. It compiles to iOS, Android, macOS, Windows, and Linux from a single codebase, with Lua and JavaScript bindings available. Monolithic structure: cocos/ directory is the engine root—cocos/2d/ contains action system (CCAction*.cpp), sprite rendering, scene graphs, and animations; cocos/ subdirectories organize by feature (3d, platform-specific, audio). CMake build system in cmake/ with platform detection and dependency discovery. Top-level examples and tests directories. GitHub workflows (.github/workflows/main.yml) drive CI; download-deps.py + git submodules manage external dependencies.

Game developers and interactive media creators who need a production-ready 2D engine supporting mobile and desktop platforms; teams building games, interactive books, and demos who want C++ performance with cross-platform deployment; contributors maintaining the engine and building on top of it for Cocos Creator 1.x and 2.x.

Highly mature and production-ready: the project has millions of active users globally, maintains dual CI pipelines (AppVeyor for Windows, Travis CI for others), uses CMake for robust multi-platform builds, and shows active development across v4 branch. The codebase spans 23M+ lines of C++ with comprehensive module organization (cocos/2d/ contains core actions, sprites, and animations). Clear versioning and detailed RELEASE_NOTES indicate professional maintenance.

Moderate complexity risks: the project integrates multiple physics engines and external dependencies (FMOD, Chipmunk, Box2D, Spine) requiring careful version coordination—see cmake/Modules/ for 20+ FindXXX dependency resolvers. Large monolithic codebase (23M lines) means changes can have wide impact. Community-driven maintenance (not a corporate entity) means occasional dependency version friction, though CI coverage via AppVeyor/Travis reduces silent breakage. Last commit recency from v4 branch indicates active but not daily-cadence updates.

Active v4 branch development indicated by CI badges and RELEASE_NOTES. The project maintains backward compatibility while modernizing the codebase. CMake migration and platform support expansion are ongoing (see cmake/Modules/ recent additions). Python dependency download system (download-deps.py) being actively maintained for dependency management.

Clone and initialize the repository with dependencies:

git clone https://github.com/cocos2d/cocos2d-x.git
cd cocos2d-x
python download-deps.py
git submodule update --init

Then follow platform-specific build instructions in CMakeLists.txt or use Xcode/Visual Studio project files included in the repo.

Daily commands: No single 'run' command—build process platform-specific:

# Linux/macOS with CMake:
mkdir build && cd build
cmake .. -GXcode  # or -G'Unix Makefiles'
cmake --build .

# Windows: Open .sln in Visual Studio or use CMake
# iOS/Android: Use provided project files or CMake with platform flags

See platform-specific build guides in docs/.

• CMakeLists.txt — Root build configuration that orchestrates the entire multi-platform compilation pipeline for iOS, Android, macOS, Windows, and Linux.
• cocos/2d/CCActionManager.h — Core action scheduling system that manages all game object animations and is a foundational abstraction used throughout the engine.
• cocos/2d/CCLayer.h — Base scene/layer abstraction for 2D games; every game scene inherits from this class, making it critical to understand game flow.
• cocos/2d/CCLabel.h — Text rendering system supporting multiple font formats (FNT, FreeType); essential for UI-heavy games and understanding font asset pipelines.
• cocos/2d/CCAnimation.h — Animation and sprite frame sequencing system; core to all character and particle animation workflows.
• cocos/2d/CCCamera.h — Camera and viewport management for scene rendering; controls how game world is projected to screen and affects performance tuning.
• cmake/Modules/CocosConfigDefine.cmake — CMake configuration definitions for feature flags and platform-specific build options; essential for cross-platform compatibility decisions.

Add a New Game Action/Animation

1. Create a new class inheriting from CCActionInterval in cocos/2d/CCActionInterval.h (cocos/2d/CCActionInterval.h)
2. Implement step(float) method to update target node properties over duration (cocos/2d/CCActionInterval.cpp)
3. Register the action in CCActionManager so it gets ticked each frame (cocos/2d/CCActionManager.h)
4. Add easing support by wrapping with CCActionEase if temporal interpolation is needed (cocos/2d/CCActionEase.h)

Add Support for a New Font Format

1. Create a new CCFont subclass in cocos/2d/CCFont.h (e.g., CCFontWebP.h) (cocos/2d/CCFont.h)
2. Implement glyph rasterization and atlas generation logic (cocos/2d/CCFontAtlas.h)
3. Register the new font loader in CCFontAtlasCache so CCLabel can use it (cocos/2d/CCFontAtlasCache.h)
4. Add CMake find module in cmake/Modules/ to detect the font library (e.g., FindMyFontLib.cmake) (cmake/Modules/FindFMOD.cmake)

Implement a Custom Tiled Map Layer with Physics

1. Load TMX file using CCFastTMXTiledMap and get CCFastTMXLayer reference (cocos/2d/CCFastTMXTiledMap.h)
2. For each tile, generate collision polygon using CCAutoPolygon from tile spritesheet (cocos/2d/CCAutoPolygon.h)
3. Attach collision component via CCComponent to layer or individual tile nodes (cocos/2d/CCComponent.h)
4. Integrate physics engine (Chipmunk) configured in cmake/Modules/FindChipmunk.cmake for collision callbacks (cmake/Modules/FindChipmunk.cmake)

Add a Custom Grid Transformation Effect

1. Create a new class inheriting from CCGridAction in cocos/2d/CCActionGrid.h (cocos/2d/CCActionGrid.h)
2. Implement the grid mesh transformation logic in the update method (cocos/2d/CCGrid.h)
3. Apply the action to a node's grid via node->runAction(newGridAction) using CCActionManager (cocos/2d/CCActionManager.h)
4. For 3D grid effects, use CCActionGrid3D or CCActionTiledGrid subclasses instead (cocos/2d/CCActionGrid3D.h)

• C++ with CMake build system — Enables native cross-platform compilation (iOS, Android, macOS, Windows, Linux) with consistent build artifacts and performance-critical runtime execution
• OpenGL/Metal rendering backend (inferred from CCCamera, rendering layers) — Provides GPU-accelerated sprite batching and efficient 2D graphics without CPU bottlenecks
• FreeType & bitmap font (FNT) support — Allows both runtime TrueType rendering and pre-baked bitmap fonts for memory-constrained mobile platforms
• TMX tilemap format (FastTMX) — De-facto standard for 2D level editors (Tiled); enables designers to iterate without code changes
• Chipmunk physics engine (optional dependency) — Lightweight 2D physics suitable for mobile devices; integrates as an optional module via CMake
• FMOD audio (optional dependency) — Cross-platform audio with advanced features (3D, streaming); integrated as pluggable module

• undefined
  • Why: undefined
  • Consequence: undefined

Must run python download-deps.py before building—skipping this causes cryptic linker errors for missing physics/audio libs. CMake generator varies by platform (Xcode for macOS, Visual Studio for Windows, Unix Makefiles for Linux)—mismatch causes build failure. Git submodules require explicit git submodule update --init after clone or pull. Platform-specific code in cocos/platform//requires correct #ifdef guards—test on actual target (iOS, Android) not just Desktop. Dependency versions in cmake/Modules/Find.cmake may conflict with system-installed versions—use -DCOCOS_PREBUILT_LIBS flag to force bundled versions.

• Scene Graph — Cocos2d-x organizes all game objects (CCNode subclasses) in a tree hierarchy—understanding parent-child transforms, z-order, and visit() traversal is essential to managing any game's visual layout.
• Action System — The core animation and behavior mechanism in cocos2d-x—actions are composable (Sequence, Spawn) and time-based, enabling smooth transitions and gameplay logic without manual delta-time management.
• Event Dispatch / Touch Input — Cocos2d-x's event system (EventDispatcher, EventListener, Touch events) handles input from mouse, keyboard, and touch in a unified way across platforms—critical for responsive game UI and gameplay.
• Skeletal Animation (Spine/Armature) — Cocos2d-x integrates Spine and Armature skeletal animation systems natively, allowing bones-based character animation rather than frame-by-frame sprites—essential for complex character rigs in modern 2D games.
• Physics Integration (Box2D/Chipmunk) — Two full physics engines (rigid body dynamics, collision detection) are built into cocos2d-x—understanding which engine to choose and how to couple physics bodies to CCNode objects is critical for physics-based gameplay.
• Sprite Sheets and Texture Atlasing — Cocos2d-x's SpriteFrameCache and texture atlases reduce draw calls and memory by packing multiple sprites into single textures—understanding frame naming and cache management is vital for performance in sprite-heavy games.
• Particle System — Built-in particle emitter system (ParticleSystem, ParticleSystemQuad) generates effects like explosions, fire, smoke with minimal code—understanding emitter properties and quad rendering is key to visual polish.

• cocos2d/cocos2d-iphone — The Objective-C predecessor that inspired cocos2d-x's architecture and design patterns; understanding this clarifies why C++ cocos2d-x made certain decisions.
• cocos2d/cocos-creator — Modern visual editor built on top of cocos2d-x; the primary way many developers now use the engine rather than writing C++ directly.
• libsdl-org/SDL — Cross-platform windowing and input library that cocos2d-x uses on desktop platforms (Windows, macOS, Linux) for window management and event dispatch.
• erincatto/Box2D — One of two integrated physics engines in cocos2d-x; many games use cocos2d-x specifically for its Box2D integration without writing raw Box2D code.
• godotengine/godot — Alternative open-source game engine in the same ecosystem; developers choose between Cocos2d-x (lighter, 2D-focused) and Godot (heavier, 3D support) for similar projects.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for CCAction and related action classes

The cocos/2d directory contains numerous action classes (CCAction.cpp/h, CCActionInterval.cpp/h, CCActionInstant.cpp/h, CCActionEase.cpp/h, etc.) but there are no visible test files for these critical game animation components. Adding comprehensive unit tests would improve reliability and prevent regressions in core animation functionality used by millions of developers.

• [ ] Create tests/2d/ActionTest.cpp with fixtures for CCAction, CCActionInterval, CCActionInstant, and CCActionEase
• [ ] Add test cases for action timing, completion callbacks, and action chaining
• [ ] Create tests/2d/ActionManagerTest.cpp to test action scheduling and lifecycle
• [ ] Integrate new tests into CMakeLists.txt and verify they run in CI pipelines (.travis.yml and .appveyor.yml)

Implement GitHub Actions workflow for cross-platform builds

The repo currently relies on legacy .travis.yml (deprecated) and .appveyor.yml for CI. The .github/workflows/main.yml file exists but is incomplete. Modernizing to GitHub Actions with support for Windows, macOS, Linux, iOS, and Android builds would provide faster feedback and reduce maintenance of external CI services.

• [ ] Expand .github/workflows/main.yml to include separate jobs for Windows (MSVC), macOS (Xcode), and Linux (GCC/Clang) builds
• [ ] Add conditional CMake configuration steps referencing cmake/Modules/* for platform-specific dependencies
• [ ] Include Android NDK build job to validate mobile targets
• [ ] Add artifact upload steps for build outputs and replace/deprecate .travis.yml and .appveyor.yml

Create comprehensive CMake dependency documentation with troubleshooting guide

The cmake/Modules/ directory contains 16+ FindXXX.cmake files for dependencies (FMOD, Chipmunk, WebSockets, etc.), but cmake/README.md is minimal. New contributors struggle with dependency resolution. A detailed guide with platform-specific instructions and common issues would reduce setup friction.

• [ ] Expand cmake/README.md with a 'Quick Start' section covering Ubuntu, macOS, Windows, iOS, and Android builds
• [ ] Document each major dependency (cocos/2d dependencies) with installation commands for each OS
• [ ] Add a 'Troubleshooting' section addressing common CMake errors (missing FMOD, GLFW3, etc.) found in FindXXX.cmake files
• [ ] Include examples showing how to enable/disable optional features via cmake flags like -DUSE_FMOD=ON

• Add unit tests for cocos/2d/CCActionInterval.cpp—currently 450+ lines of animation logic with minimal test coverage; start by writing tests for Move, Rotate, and Scale actions.
• Document the action composition pattern in the Programmers Guide—Sequence and Spawn are powerful but examples/tests/ show minimal usage; create a tutorial explaining temporal composition with code samples.
• Investigate and add FindGLES.cmake module—GLES2/GLES3 support is incomplete in cmake/Modules/; mobile platforms need proper OpenGL ES detection and flags.

The cocos2d-x codebase shows a moderate security posture. While no critical vulnerabilities were identified from the visible file structure, several medium and low-risk issues exist: (1) Insecure HTTP URL in documentation, (2) potential SQL injection risks from SQLite integration without visible sanitization, (3) complex external dependency chains requiring regular auditing, and (4) missing security documentation and policies. The project is a mature, widely-used framework, but would benefit from enhanced security documentation, automated dependency scanning, and explicit secure coding guidelines for contributors. Comprehensive code review of database operations, input validation, and network communications is recommended.

• Medium · Insecure HTTP URL in README — README.md. The README contains an HTTP URL for loading an image resource (http://www.cocos2d-x.org/attachments/801/cocos2dx_portrait.png). This could be vulnerable to man-in-the-middle attacks and mixed content warnings. Should use HTTPS instead. Fix: Replace HTTP with HTTPS: https://www.cocos2d-x.org/attachments/801/cocos2dx_portrait.png
• Medium · Potential SQLite3 Integration Without Input Validation — cmake/Modules/FindSQLite3.cmake, cocos/2d components. The project includes FindSQLite3.cmake module, indicating SQLite3 database usage. If SQL queries are constructed using string concatenation or sprintf, this could lead to SQL injection vulnerabilities. File structure suggests database operations in cocos/2d components but actual implementation requires code review. Fix: Ensure all SQLite3 queries use prepared statements with parameterized queries. Implement input validation and sanitization for all user-supplied data used in SQL queries.
• Low · Build System Complexity and External Dependencies — CMakeLists.txt, cmake/Modules/. The CMakeLists.txt and multiple FindXXX.cmake modules indicate dependency on numerous external libraries (FMOD, OpenGL, Websockets, WebP, etc.). Complex dependency chains increase attack surface. Some libraries may have outdated versions or known vulnerabilities. Fix: Regularly audit and update all external dependencies. Maintain a Software Bill of Materials (SBOM). Implement dependency version pinning and use security scanning tools like Dependabot or Snyk.
• Low · Missing Security Headers Documentation — Documentation/Configuration. No visible security headers configuration or documentation for web-based components. If cocos2d-x is used for web builds or interactive applications, security headers (CSP, X-Frame-Options, etc.) may not be enforced. Fix: Add security headers configuration documentation. For web-based deployments, implement CSP, X-Frame-Options, X-Content-Type-Options, and other relevant security headers.
• Low · Incomplete Security Configuration Visibility — .travis.yml, .appveyor.yml, .github/workflows/main.yml. CI/CD configurations (.travis.yml, .appveyor.yml, .github/workflows/main.yml) are present but content is not provided for review. These could contain exposed credentials, insecure build practices, or insufficient security testing. Fix: Review CI/CD pipeline configurations for: secrets management (use GitHub Secrets), secure artifact handling, SAST/DAST integration, and signed releases. Avoid committing credentials or API keys.
• Low · Submodules Security — .gitmodules. The .gitmodules file indicates external submodules are used. Submodules can introduce security risks if they reference repositories with vulnerabilities or if commits are not pinned to specific verified versions. Fix: Pin all git submodules to specific commit hashes rather than branches. Regularly audit submodule sources. Consider using dependency scanning for submodule vulnerabilities.
• Low · Lack of Security Policy Documentation — Root directory. No visible SECURITY.md file or security policy documentation found in standard locations. This makes it unclear how security vulnerabilities should be reported. Fix: Create a SECURITY.md file in the repository root documenting: responsible disclosure process, how to report vulnerabilities, security contact information, and expected response times.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.