[IMPORTANT] Android 16K Update Guide

Cocos Creator
1

Hello developers,

To improve the engine compatibility and performance on certain Android devices (for example terminals with ARM64 architecture), we recently implemented support for the Android 16KB memory page size feature. The related code changes are ready — we hereby invite you to integrate and test them to help ensure stability and reliability of this update.

:bullseye: Core contents of this update

  1. Engine core repository (engine)
  • Contents: Key code changes that add support for Android 16KB page size.
  • Status: Submitted as PR #18910 and awaiting merge and tests.
  1. External dependency repository (external)
  • Contents: Mainly upgrades V8 version (11.8 → 12.7.140) to match the new feature. See PR #499.

:counterclockwise_arrows_button: Alternative: avoid package size increase from V8 upgrade

If you prefer not to upgrade V8 (for example to control package size), we provide alternatives:

  1. Engine code changes: manually apply the code changes referenced in the engine PR #18999 to your engine version.
  2. external V8 libraries: update V8 libs (including x64 and arm64) from the provided PR #501.

:test_tube: Key testing areas and requested feedback

Please test the following scenarios and report any issues:

  • Core regression testing: verify basic engine functionalities on ARM64 Android devices (especially devices using 16KB page size).
  • Compatibility: check for any project compatibility issues before and after the V8 upgrade.
  • Performance: monitor changes in startup time, memory footprint, and JS execution performance.
  • Stability: run long-duration tests to detect crashes or memory leaks.

:rocket: How to start testing

  1. Get the code:
  • Switch to the repository branch v3.8.7-16k and build from that branch.
  • The external repo uses large files — please install git-lfs before downloading.
  1. Prepare the environment:
  • [Strongly recommended] Upgrade your development environment: update Android Studio to 2024 or later to ensure the build process handles new dependencies and configurations.
  • [Important] Clean local project:
    • If you already have a built Android project locally, please BACK UP your project’s native directory (if you have custom changes).
    • DELETE the native directory and related build caches (e.g. build), then rebuild to ensure all native dependencies are correctly updated.

For Cocos Creator 2.x users

Cocos Creator 2.x users please refer to the engine-native repo PR #4403 for validation. During verification, ensure you use NDK 28 or newer.

1 Like
3

Thanks for this notice.

Is this fix implemented over the v3.8.7 release? In case yes, the only needed step would be to do the engine update?

4

it’s just an example for 3.8.7, follow the PRs, it could be used for 3.6. and 3.7.x as well

5

So, just to be clear, the solution was not shipped together with v3.8.7 as the default, and we must follow this solution to provide support?

6

it’s not merged into 3.8.7 yet, you need to use the custom engine from the repo v3.8.7-16k, or you could use the PR for other versions

7

Thank you for the confirmation!

8

Could you please share with me necessary changes I need to make to support 16KB architecture in my published cocos2d game ?

For your information? I use
#define COCOS2D_VERSION 0x00031702

AGP 8.6.1
Gradle 8.7
and I am enforcing build to be with ndkVersion “28.0.12433566”, as it was recomended by google developer team

As a side note, The emulator I use to test 16 KB support is Pixel 7a API 35 16KB which requires x86_64, and when I add PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86:x86_64 to gradle.properties, the build is unable to build binaries for that architecture, and it gives this error ninja: error: '../../../../../../cocos2d/external/Box2D/prebuilt/android/x86_64/libbox2d.a', needed by '../../../../build/intermediates/cxx/Debug/244g6tt4/obj/x86_64/libMyGame.so', missing and no known rule to make it

So, 2 issues I raised here, first unable to test on android emulator with 16KB architecture because it supports only x86_64, and the second issue is what are necessary configurations to add to support 16 KB

Could you assist me please, any help is appreciated !

1 Like
9

I’m using Cocos Creator 1.9.3 and can’t update right now because I’m using modified custom engines. When I run the compiled app on Android with 16 KB support, I get a crash on startup due to an out-of-memory error from the v8 library. Could you please tell me how to fix this?

10

Is there any update on this topic? When will the new release supporting 16KB for Android be available? I’m using Cocos v2—will it be supported in the next release? I’ve received a warning that the app must be updated before November 1st.

1 Like
11

We dont have a plan for new release for these days. I suggest you have try on the method we mentioned above.

1 Like