cocos-engine: the C++ runtime underneath Cocos Creator

The runtime half of Cocos Creator, not a standalone engine

The most important sentence in this README is a boundary statement rather than a feature claim. The repository is the runtime framework for the Cocos Creator editor, and the project states plainly that it is naturally integrated within that editor and designed to only be the essential runtime library, not to be used independently. Anyone evaluating it as a standalone engine to link into their own toolchain is reading past the project's own position.

What the tree contains tells you the same thing from a different angle. There is no `samples/` directory and no standalone application entry point. Instead there is `cocos/`, which holds the engine's own modules, `editor/` for editor-facing integration, `exports/` and `templates/` for what gets exposed to projects, `extensions/` and `vendor/` for third-party code, `native/` for the platform layer, and `scripts/` for the build tooling that stitches a release together. The `docs/` directory holds the coding style guides the contribution process depends on, including `CPP_CODING_STYLE.md` and `TS_CODING_STYLE.md`.

The versioning is also editor-coupled. The package name is `cocos-creator`, the package version reads 3.8.9, and the default branch is `v3.8.9`. There is a `verify:engine-version` script and a matching `update:engine-version` script that runs `node ./scripts/checkout-engine-version.js`, which is the shape you would expect from a repository whose releases track an editor's requirements rather than a standalone library's own cadence.

Two commands to a working development environment

The setup section is short enough to reproduce without notes. Prerequisites are Node.js v9.11.2 or newer and gulp-cli v2.3.0 or newer, then a clone of the repository, then one command in the engine folder:

# download & build engine dependencies
npm install

The README states that this is all you have to do to set up the engine development environment. Outside the editor, the build is a second command:

npm run build

The `package.json` shows what that actually fans out into. `build` runs `build:min` and then `build:declaration`; `build:min` is `npm run build:debug-infos && node ./scripts/build-h5-minified`, and `build:declaration` is `build:const` plus `node ./scripts/build-declarations`. There is also a `build:dev` target that produces unminified H5 source, which is the one you would want while reading engine code rather than shipping it. The scripts that matter for correctness rather than output are just as visible:

+"test": "tsc --noEmit && jest",
"test:dts": "npx tsc ./scripts/test-declarations/test.d.ts",
"verify:engine-version": "node ./scripts/verify-engine-version.js"

A type check running ahead of Jest means a large fraction of engine regressions surface as compile errors rather than test failures, which is a reasonable arrangement for a codebase this size. The README also notes that if you are running inside Cocos Creator, the engine compiles automatically once the editor window opens, and that native application work has its own instructions in `native/README.md`.

Why half the engine is C++ and half is TypeScript

The README names the split directly: the runtime engine is built with half C++ and half TypeScript, with low-level infrastructure, native platform adaptation, the renderer and scene management all written in C++ to ensure high runtime performance. It adds that the project keeps moving heavy lifting work to native as much as possible. The reason is not aesthetic. Anything on the per-frame path in a game loop, which is to say rendering and scene traversal, pays a cost per call, and a TypeScript boundary there is a boundary you pay on every frame rather than once at load.

The user-facing half is where TypeScript earns its place. The README describes an easy TypeScript API as one of the six headline features, and the user-level API set is provided in TypeScript alongside editor support in VSCode. That choice has a practical consequence for the API surface: `typedoc.json` and `typedoc-index.ts` sit at the repository root, and the `build:declaration` script exists specifically to emit type declarations, with a separate `test:dts` job that type-checks the declaration output. Declarations are a first-class artifact here, which tells you the engine is consumed by a typed toolchain on the other side of the boundary.

There is also a `@types/` directory and an `EngineErrorMap.md` at the root, which suggests error codes are enumerated rather than thrown as loose strings. For a game engine that other people's build pipelines have to survive, that kind of bookkeeping is the difference between a bug report you can act on and one you cannot.

GFX and a render pipeline meant to be rewritten

Graphics is the part of the repository with the most specific technical claims, and the claims are concrete enough to check against the source. The GFX implementation is described as designed to adapt to modern graphics APIs: Vulkan on Windows and Android, Metal on macOS and iOS, and WebGL on web platforms. The repository topics list `metal`, `vulkan`, `webgl`, `webgl2` and `webgpu` alongside `3d` and `game-development`, which is consistent with a graphics abstraction layer that has to span five backends.

The render pipeline is listed as fully customisable, with builtin forward and deferred render pipelines supported across all platforms and developers able to customise the pipeline following the same approach. That word choice matters. A pipeline described as configurable is a set of switches; a pipeline described as fully customisable, in a runtime where scene management and the renderer are native code, is closer to source you rewrite per project. Cocos Creator makes that path practical through the custom engine workflow the README points to for contributors: fork, then configure a custom engine in the editor.

The shading story is described in the same register. The material system is built on the effect format using GLSL 300, with shader programs converted automatically to a suitable runtime format, which is what allows one authoring language to target several backends. The standard effect adopts physically based rendering, with a physically based camera and lighting based on physical metrics. A surface shader that permits full customisation of the surface material while keeping a universal lighting model is a reasonable middle position for teams that want a distinct look without writing a lighting model from nothing.

One codebase, from Windows desktops to mini games

The platform list in the README is unusually wide, and it is worth separating what it says from what it implies. Named targets are Windows, Mac, iOS, Android, HarmonyOS, Web, Facebook Instant Games, WeChat Mini Game and TikTok Mini Games. Native platforms, web platforms and what the README calls rapidly expanding instant gaming platforms are all in scope for the same engine, with instant preview built in alongside animation, physics, particle, terrain editing and a complex UI system.

The mini game targets are the interesting constraint. They run inside host platforms with their own runtime rules, distribution and capability sets, which is why they appear alongside desktop and mobile rather than as an afterthought. Adapting to a host's rules is native platform work, and native platform work is exactly what the README says is written in C++, so the split described earlier and the platform list described here are two views of the same decision.

What the README does not do is quantify any of it. There are no frame rate figures, no package size numbers, no comparison against another engine, and no statement about which of those nine targets sees equal feature support. The renderer is native code and the pipeline is customisable, so performance characteristics are determined largely by what a project does with it. A reader looking for a benchmark table will not find one here, and the repository offers no single place that substitutes for it.

What a pull request has to clear before it lands

The contribution notice is the most concrete documentation in the repository, and it reads like a real review process rather than a formality. A pull request is expected to follow the C++ coding style guide and the TypeScript coding reference, to integrate ESLint and the C++ auto fix tools into the coding environment, to link related issues or discussions and clearly state its purpose, to pass all automatic continuous integration tests, to request review from file owners or engine developers, and to get one valid approval from the engine architects.

Two of those requirements are unusual enough to notice. Requiring a valid approval from the engine architects means review capacity, not just reviewer availability, sits on the critical path for every change, and that is a structural fact about the project rather than a policy statement. Requiring ESLint and the auto fix tools locally shifts lint failures from CI onto the author's machine before the request exists.

The repository layout supports the process rather than merely describing it. There is a `.circleci/` directory for continuous integration, a `.eslintrc.yaml` with a companion `.eslintignore`, an `.editorconfig`, a `jest.config.js`, and a `tests/` directory. Contribution is not limited to code: the README asks for bug reports and feature requests through the issue tracker, participation in issue discussions, documentation improvements in the separate usage documentation repository, and help in the forum.

Editorial conclusion

cocos-engine is a component, not a product you adopt on its own. The README is explicit that it is designed to be the essential runtime library for the Cocos Creator editor rather than something used independently, and that shapes every decision in the repository. What it does offer a reader is a clear look at how a commercial engine splits work between native code for rendering, scene management and platform adaptation, and TypeScript for the API a game actually touches. The graphics story is the most concrete part: GFX maps to Vulkan on Windows and Android, Metal on macOS and iOS, and WebGL on web, with a render pipeline the project expects you to modify rather than merely configure. The last push was on 2026-09-21 and release 3.8.8 shipped on 2025-12-16, so the line is moving. If you want to change how this engine draws, fork the repository, point a Cocos Creator editor at your copy through the custom engine workflow, and read native/README.md before touching the platform layer.

Frequently asked questions

Official sources

1. cocos/cocos-engine on GitHub
2. Issues
3. Project website
4. README
5. Releases