Cocos Game Developer: từ JD đến offer 🏠
🏠 Trang chủ / Cocos Game Developer: từ JD đến offer / Phần 3 · Native, SDK, build & phát hành / Module 13
🤖 Module 13 / 21 · 1 tuần Nâng cao

Native bridge Android: JNI, Java ↔ C++/TypeScript và luồng xử lý

JNI từ gốc: JNIEnv, chữ ký phương thức, tham chiếu local/global. Gọi Java từ C++ (Cocos2d-x) và từ TypeScript (Creator 3.x reflection), gọi ngược Java → game, ba luồng (UI, game/GL, nền) và cách chuyển qua lại, giữ class khỏi R8/ProGuard, gỡ lỗi JNI thường gặp.

JNIJniHelpernative.reflectionJsbBridgeThreadR8
🎯 Dòng JD mà module này giúp bạn đáp ứng
  • “Build and maintain native bridges (JNI for Android ...)”
  • “Experience building native bridges (JNI for Android, Objective-C/C++ for iOS)”
📌 Vì sao nhà tuyển dụng hỏi phần này

Mọi SDK (quảng cáo, thanh toán, đăng nhập, rung, chia sẻ) đều đi qua cầu nối native. Lỗi ở đây là crash native khó đọc hoặc lỗi “thỉnh thoảng không nhận thưởng”. Người phỏng vấn hỏi để biết bạn từng tự viết cầu nối hai chiều và xử lý luồng, hay chỉ dùng plugin có sẵn.

🎯 Mục tiêu học tập

  • Đọc/viết chữ ký JNI, quản lý tham chiếu local/global
  • Gọi Java từ C++ (2d-x) và từ TS (Creator)
  • Gọi ngược từ Java về game an toàn
  • Chuyển luồng đúng: UI ↔ game ↔ nền
  • Cấu hình R8/ProGuard và gỡ lỗi JNI

🟢 JNI trong 10 phút

Kiểu JavaChữ kýVí dụ chữ ký phương thức
voidVvoid showBanner() → ()V
booleanZboolean isReady(String id) → (Ljava/lang/String;)Z
int / longI / Jvoid vibrate(int ms) → (I)V
float / doubleF / Dfloat getScale() → ()F
StringLjava/lang/String;String getDeviceId() → ()Ljava/lang/String;
int[][Ivoid setLevels(int[] a) → ([I)V
  • JNIEnv* gắn với từng luồng; không lưu JNIEnv để dùng ở luồng khác.
  • Đối tượng Java trả về/ tạo trong native là local reference, tự giải phóng khi hàm native trả về Java. Nhưng trong vòng lặp dài ở native, phải DeleteLocalRef, nếu không sẽ tràn bảng tham chiếu (local reference table overflow).
  • Muốn giữ đối tượng Java qua nhiều lần gọi: NewGlobalRef, và nhớ DeleteGlobalRef.

🟡 Cocos2d-x: C++ gọi Java và Java gọi C++

// C++ → Java (static method)
#include "platform/android/jni/JniHelper.h"
using cocos2d::JniHelper;

void NativeBridge::showRewarded(const std::string& placement) {
    // Cách gọn (Cocos2d-x 3.17+): template tự suy ra chữ ký
    JniHelper::callStaticVoidMethod("org/cocos2dx/cpp/AdBridge", "showRewarded", placement);
}

bool NativeBridge::isRewardedReady(const std::string& placement) {
    // Cách thủ công: hiểu rõ để gỡ lỗi
    cocos2d::JniMethodInfo t;
    bool ok = false;
    if (JniHelper::getStaticMethodInfo(t, "org/cocos2dx/cpp/AdBridge", "isRewardedReady", "(Ljava/lang/String;)Z")) {
        jstring jp = t.env->NewStringUTF(placement.c_str());
        ok = t.env->CallStaticBooleanMethod(t.classID, t.methodID, jp);
        t.env->DeleteLocalRef(jp);
        t.env->DeleteLocalRef(t.classID);
    }
    return ok;
}
// Java → C++: khai báo native method, gọi từ Java khi SDK báo thưởng
package org.cocos2dx.cpp;

public class AdBridge {
    public static native void nativeOnRewarded(String placement, int amount);   // cài đặt ở C++

    // SDK callback thường chạy trên UI thread → chuyển sang GL/game thread trước khi gọi native
    static void onSdkRewarded(final String placement, final int amount) {
        AppActivity.getInstance().runOnGLThread(() -> nativeOnRewarded(placement, amount));
    }
}
// C++: tên hàm phải khớp package + class + method (dấu chấm → gạch dưới)
extern "C" JNIEXPORT void JNICALL
Java_org_cocos2dx_cpp_AdBridge_nativeOnRewarded(JNIEnv* env, jclass, jstring jPlacement, jint amount) {
    std::string placement = cocos2d::JniHelper::jstring2string(jPlacement);
    // Đã ở GL thread nhờ runOnGLThread; nếu không chắc, chuyển tiếp lần nữa cho an toàn:
    cocos2d::Director::getInstance()->getScheduler()->performFunctionInCocosThread([placement, amount] {
        RewardService::instance().grant(placement, amount);
    });
}
AppActivity.getInstance()

Hàm này là ví dụ: bạn tự lưu tham chiếu Activity (static) trong onCreate, hoặc truyền Activity khi khởi tạo bridge. Cẩn thận rò rỉ Activity khi lưu static: xoá ở onDestroy.

🟡 Cocos Creator 3.x: TypeScript ↔ Java

// TypeScript → Java bằng reflection (static method, trả về giá trị nguyên thuỷ/ chuỗi)
import { native, sys } from 'cc';

export function vibrate(ms: number) {
    if (sys.os === sys.OS.ANDROID && sys.isNative) {
        native.reflection.callStaticMethod('com/cocos/game/DeviceBridge', 'vibrate', '(I)V', ms);
    }
}
export function deviceRamMb(): number {
    if (!(sys.isNative && sys.os === sys.OS.ANDROID)) return 4096;
    return native.reflection.callStaticMethod('com/cocos/game/DeviceBridge', 'totalRamMb', '()I') as number;
}
// Kênh hai chiều gọn hơn: JsbBridge (truyền 2 chuỗi; đóng gói JSON nếu cần nhiều tham số)
// TypeScript
import { native } from 'cc';
native.bridge.onNative = (event: string, payload?: string) => {
    if (event === 'ad_rewarded') RewardService.grant(JSON.parse(payload!));
};
native.bridge.sendToNative('show_rewarded', JSON.stringify({ placement: 'double_coins' }));
// Java (thư mục native/engine/android/app/src/... của project Creator — nhớ commit)
import com.cocos.lib.JsbBridge;
import com.cocos.lib.CocosHelper;

public class BridgeSetup {
    public static void init() {
        JsbBridge.setCallback(new JsbBridge.ICallback() {
            @Override public void onScript(String event, String payload) {      // từ TS gửi xuống
                if ("show_rewarded".equals(event)) AdManager.showRewarded(payload);
            }
        });
    }
    // Gọi từ callback SDK (UI thread): chuyển về game thread rồi gửi lên script
    public static void notifyRewarded(final String json) {
        CocosHelper.runOnGameThread(() -> JsbBridge.sendToScript("ad_rewarded", json));
    }
}
Kiểm tra theo phiên bản

Tên namespace đã đổi giữa các bản (2.x/ đầu 3.x dùng jsb.reflection, các bản 3.x sau dùng native.reflection; package Java org.cocos2dx.lib → com.cocos.lib). Khi phỏng vấn, nói rõ bạn dùng phiên bản nào và sẽ tra tài liệu tương ứng: đó là dấu hiệu của người làm thật.

🔴 Ba luồng và quy tắc chuyển

LuồngAi chạy ở đâyQuy tắc
UI thread (main) AndroidActivity, View, phần lớn callback SDKHiện UI SDK (quảng cáo, hộp thoại) ở đây: runOnUiThread
Game/ GL threadVòng lặp Cocos, script, nodeMọi thao tác node/ script ở đây: runOnGLThread (2d-x), CocosHelper.runOnGameThread (Creator)
Luồng nềnMạng, IO, xử lý nặngKhông chạm UI hay node; trả kết quả qua hai luồng trên
Vòng đời một lần xem quảng cáo nhận thưởng
TS: sendToNativegame thread
Java nhậngame thread
runOnUiThreadhiện quảng cáo
SDK callbackUI thread
runOnGameThreadsendToScript

Triệu chứng sai luồng: crash “CalledFromWrongThreadException” (đụng View từ game thread), crash ngẫu nhiên trong engine (đụng node từ UI thread), hoặc callback “mất” vì script chưa sẵn sàng.

🟡 R8/ProGuard và gỡ lỗi

# proguard-rules.pro: giữ class/ method được gọi bằng tên qua JNI/ reflection
-keep class com.cocos.game.DeviceBridge { public static *; }
-keep class com.cocos.game.BridgeSetup { *; }
-keepclasseswithmembernames class * { native <methods>; }   # giữ tên native method
LỗiNguyên nhân thường gặp
NoSuchMethodError/ ClassNotFound khi releaseR8 đổi tên/ xoá class; chữ ký sai; sai đường dẫn package
UnsatisfiedLinkErrorTên hàm C++ không khớp package/class; thư viện .so chưa nạp; thiếu ABI
local reference table overflowTạo jstring/ jobject trong vòng lặp không DeleteLocalRef
Crash ngẫu nhiên sau callbackĐụng node từ UI thread
Chạy debug được, release lỗiR8, khác ABI, khác cấu hình build

Công cụ: adb logcat lọc theo tag, bật CheckJNI trên bản debug (adb shell setprop debug.checkjni 1 với máy phù hợp/ emulator) để bắt lỗi JNI sớm, ndk-stack để đọc stack native.

🎤 Câu hỏi phỏng vấn thường gặp (trả lời to trước khi mở)

🎤 Mô tả cách bạn gọi một hàm Java từ game và nhận kết quả bất đồng bộ trở lại.
Game (C++/TS) gọi static method qua JniHelper/ native.reflection hoặc JsbBridge.sendToNative; Java chuyển sang UI thread để gọi SDK; SDK callback trên UI thread; Java chuyển về game thread (runOnGLThread/ CocosHelper.runOnGameThread) rồi gọi native method/ sendToScript; game cập nhật trạng thái. Nêu chữ ký, xử lý timeout, giữ class khỏi R8.
🎤 Local reference và global reference khác nhau thế nào?
Local hợp lệ trong lần gọi native hiện tại, tự giải phóng khi trả về Java; bảng có giới hạn → vòng lặp phải DeleteLocalRef. Global sống đến khi DeleteGlobalRef, dùng để giữ jobject/ jclass qua nhiều lần gọi hoặc giữa các luồng.
🎤 Bản debug chạy, bản release gọi native bị NoSuchMethodError. Vì sao?
R8/ProGuard xoá hoặc đổi tên class/method chỉ được gọi bằng tên qua JNI/ reflection. Thêm keep rule; kiểm tra mapping.txt; viết test smoke trên bản release.
🎤 Tại sao không được cập nhật node trực tiếp trong callback SDK Android?
Callback chạy trên UI thread, engine không thread-safe → crash ngẫu nhiên/ dữ liệu hỏng. Chuyển về game thread trước.
🎤 JsbBridge khác reflection thế nào, bạn chọn cái nào?
Reflection gọi static method trực tiếp theo tên + chữ ký, đồng bộ, trả về giá trị nguyên thuỷ/ chuỗi — tiện cho truy vấn đơn giản. JsbBridge là kênh sự kiện hai chiều (2 chuỗi), hợp cho luồng bất đồng bộ, tập trung một chỗ. Dự án lớn: một lớp bọc thống nhất trên JsbBridge + JSON.

⚠️ Sai lầm thường mắc

❌ Đụng View từ game thread / node từ UI thread

Vì sao nguy hiểm: Crash ngẫu nhiên.

Cách làm đúng: Luôn chuyển luồng rõ ràng.

❌ Không DeleteLocalRef trong vòng lặp

Vì sao nguy hiểm: Tràn bảng tham chiếu.

Cách làm đúng: Xoá sau mỗi lần dùng.

❌ Thiếu keep rule

Vì sao nguy hiểm: Release crash, debug chạy.

Cách làm đúng: Keep class/method gọi qua JNI/ reflection.

❌ Lưu Activity vào static mãi

Vì sao nguy hiểm: Rò rỉ Activity.

Cách làm đúng: Xoá tham chiếu ở onDestroy, dùng WeakReference khi phù hợp.

❌ Mỗi tính năng một kiểu bridge

Vì sao nguy hiểm: Khó bảo trì.

Cách làm đúng: Một lớp bridge tập trung, giao thức JSON có version.

❌ Không xử lý callback không bao giờ về

Vì sao nguy hiểm: Game treo chờ phần thưởng.

Cách làm đúng: Timeout + trạng thái hiển thị.

📌 Cần nhớ
  • Chữ ký JNI: (tham số)kiểu trả về; String = Ljava/lang/String;
  • Local ref tự giải phóng khi về Java; global ref phải xoá.
  • 2d-x: JniHelper; Creator: native.reflection hoặc JsbBridge.
  • UI thread cho SDK/ View; game thread cho node/ script; chuyển luồng bắt buộc.
  • Keep rule R8 cho mọi thứ gọi bằng tên.

🧩 Tự kiểm tra (bấm để xem đáp án)

1. Chữ ký của static boolean isReady(String id):
A. (Ljava/lang/String;)Z
B. (String)boolean
C. (Z)Ljava/lang/String;
Đáp án: A. Tham số trong ngoặc, kiểu trả về sau.
2. Callback SDK chạy trên UI thread muốn cập nhật node, cần:
A. Gọi trực tiếp
B. Chuyển về game/GL thread
C. Dùng setTimeout
Đáp án: B. Engine không thread-safe.
3. UnsatisfiedLinkError thường do:
A. Tên hàm C++ không khớp package/class hoặc thư viện chưa nạp
B. Thiếu ảnh
C. Sai font
Đáp án: A. Liên kết native thất bại.
4. Giữ một jobject qua nhiều lần gọi native:
A. Lưu local ref
B. NewGlobalRef + DeleteGlobalRef khi xong
C. Không thể
Đáp án: B. Local ref hết hạn.
5. Bản release lỗi NoSuchMethodError, bản debug không:
A. R8/ProGuard
B. Màn hình
C. Wi-Fi
Đáp án: A. Rút gọn code đổi tên/ xoá.

🏋️ Bài tập thực hành

DeviceBridge hai chiều

Viết bridge (Creator 3.x hoặc 2d-x) gồm: rung (TS→Java), lấy RAM/ model (TS→Java có trả về), mở hộp thoại native xác nhận thoát và trả kết quả về game (bất đồng bộ, đúng luồng), lắng nghe sự kiện pin yếu đẩy lên game. Build release có R8 bật và chứng minh mọi chức năng chạy.

💡 Gợi ý lời giải
Hộp thoại: Java nhận lệnh trên game thread → runOnUiThread(AlertDialog) → nút bấm → CocosHelper.runOnGameThread(() -> JsbBridge.sendToScript('exit_confirm', 'yes')). Pin yếu: BroadcastReceiver ACTION_BATTERY_LOW. Kiểm tra R8: chạy bản release, lọc logcat. RAM dùng cho chọn quality ở module 11.

📚 Tài nguyên học tập

✅ Tự đánh giá hoàn thành

  • Viết 6 chữ ký JNI
  • Gọi Java từ C++ hoặc TS
  • Gọi ngược về game đúng luồng
  • Viết keep rule
  • Làm bài tập DeviceBridge
Lưu ý: Cocos Creator, Cocos2d-x, Spine, SDK của Google/ Apple/ các mạng quảng cáo thay đổi API theo phiên bản. Code mẫu viết cho Cocos Creator 3.8.x và Cocos2d-x 3.17/4.0; luôn đối chiếu tài liệu chính thức của phiên bản dự án bạn đang dùng. Chính sách App Store/ Google Play (đăng nhập, quyền riêng tư, tải code, target API) được tóm tắt ở mức tham khảo, hãy đọc bản mới nhất trước khi phát hành. Khoá học độc lập, không liên kết với Cocos, Esoteric Software hay nhà tuyển dụng nào.