Cocos2d-x V4.0 released

After one year’s hard work, we are happy to announce that cocos2d-x v4.0 is released. If you want metal support on iOS/macOS, then you should use this version. If not, then you can still use v3.x.

Spine runtime is not included in the zip file as the codes is not merged in Spine runtime official repo. But you can check out the PR to use spine runtime. Or you can get the patch file and do patch by yourself. The patch file is generated by git diff commands.


Cocos2d-x v4.0.
MD5: 2b85309a729ddcdc3ac95b6985d25b83


  • support metal on iOS/macOS
  • use CMake for all platforms
  • update GLFW to 3.3
  • update minizip to 1.2
  • remove deprecated functions
  • remove h5 engine and JSB
  • remove tiff
  • remove SimpleAudioEngine
  • remove experimental namespace
  • fix bug that system font can not work correctly on macOS 15
  • fix lua crash on 64-bit devices
  • fix bugs for iOS 13
    • UIWebView uses WKWebView instead
    • VideoPlayer uses AVPlayerController instead


We wrote some documentations to help developers upgrade to v4:


Congratulations @zhangxm @coulsonwang @PatriceJiang. The team worked so hard in this release.

Everyone, please join me in thanking the team.



Besides Metal support, is this a relatively minor update from cocos2d-x 3.x? Feature list seems to mostly be updating libraries and removing outdated libraries and code. No significant changes to functionality?

Yep, but because of metal support, the rendering mechanism changes, and it may fix many rendering bugs that using global GL state.

1 Like

Few questions:

  • Do you have any performance tests to compare v4 vs v3 renderer? (I am interested mainly in iOS, Android)
  • Will you close branch v3 and continue development in v4 only?

Is there any rendering performance gain on Apple products in v4 using Metal over v3 using OpenGL?
Would be interested to see any performance metrics.



Congratulations. Thanks for the hard work.

Congradulations guys! ) Thanks for all the hard work! )

Though its have some major issues about metal, like its crashing if device doesn’t support metal.
Thank you.

I saw your topic about this crash and I have tagged @zhangxm and he will have the team look.

1 Like

Wait what!?
Support Metal = No longer support OpenGL???
This wording is completely wrong. It isn’t ‘support meta’ but ‘replace opengl rendering with metal’

This fundamentally changes the supported device spectrum for cocos2dx.
The github still states ‘iOS 8+’ which is no longer the case.

The new requirements will be ‘Metal-supported iOS device: iPhone 5S or newer, iPad Air or newer’ (see

Was this confirmed anywhere until this sudden release? Even I had the understanding that opengl remained as a side-by-side renderer option???

(Just to add: we clearly understood that custom GL commands would no longer work in platform-agnostic code, but presumed this was to handle both renderers, not that GL was being fully removed.

For reference, we would lose X% users by dropping support for OpenGL-only devices meaning the metal upgrade no longer holds enough value until Apple forces a move away from OpenGL)

Congratulation to the entire team!
Everyone here appreciates how hard it is to work on such a complex project!

Thanks for this release, guys!

My Congratulation!

But could you please clarify some things:

  1. The following part of TextureCube::init function:

     backend::PixelFormat  ePixelFmt;
     unsigned char*          pData = getImageData(img, ePixelFmt);
     uint8_t *cData = nullptr;
     uint8_t *useData = pData;

getImageData(…) set ePixelFmt to AUTO value despite the img->_pixelFormat is equal RGBA8888. In result of that I catch
CCASSERT(false, "error: CubeMap texture may be incorrect, failed to convert pixel format data to RGBA8888");
in some lines later.

I set ePixelFmt to RGBA8888 forcibly and the initializing passed well.

  1. The second question touches of the RenderTexture class.
    I created custom RenderTextureCustom which based on cocos2d::RenderTexture. It supports rendering to the texture of 3D objects, and can support optionally only depth attachment if needed (without color attachment).

I have the issue on Window in the following sequence steps

first step: Rendering to FrameBuffer with only depth attachment texture;
second step: Rendering to FrameBuffer with only color attachment texture.
issue: No any color data in the color attachment texture after second step.

After some research I found that there is color attachment disabling in the backend/opengl/CommandBufferGL.cpp inside CommandBufferGL::applyRenderPassDescriptor, if color attachment is absent for FrameBuffer (first step). But there is no color attachment enabling after that which cause to the issue I mentioned.

I fixed this with following lines inside the same function:

I would appreciate if you suggest something better.

And one more question. Have you in plan to support multiple color attachments?

@nirobkuet @Guykun v3 is still available. And v4 only supports metal is known if you focus other versions such alpha, beta, rc0 …

@coulsonwang pleas take a look of @solan’s issue.

fixed in PR 20397. For AOTU pixel format it dose not need to convert to RGBA8888.

Congratulations. Thanks for your hard work. But why JSB was removed?

  1. first step: It will create an FBO and adds a depthAttachmentTexture;
  2. second step: Since the FBO has always created in the first step, so it simply adds a colorAttachmentTexture to the FBO if you want to render it to a texture.

So why there is no color attachment enabling? Or can you provide me a demo?