Cocos gameloader — Maven 集成

面向 宿主 App（应用商店 / 大厅）接入已发布的 gameloader AAR，下载并运行 Cocos Creator 2.4.15 jsb-link 游戏包。

只需依赖一个坐标，libcocos2dx、apk-expansion-zipfile、okhttp 由 POM 传递依赖自动拉齐。

快速体验成品底座见快速演示。

1. 坐标与产物

坐标	版本示例	说明
`com.qcode.cocosstroe:gameloader`	`1.0.7.20260810`	主库：下载缓存 + 引擎启动 + `libcocos2djs.so`
`com.qcode.cocosstroe:libcocos2dx`	`2.4.15`	Cocos Java 桥（传递）
`com.qcode.cocosstroe:apk-expansion-zipfile`	`1.0`	Play Expansion 辅助（传递）
`com.squareup.okhttp3:okhttp`	`3.12.13`	下载用（传递）

版本号以 Nexus maven-releases 实际发布为准。

2. 仓库配置

正式产物：

text

http://nexus.cluster.qcast.cn/repository/maven-releases/

根工程 build.gradle：

groovy

allprojects {
    repositories {
        maven {
            url "http://nexus.cluster.qcast.cn/repository/maven-releases/"
            allowInsecureProtocol = true
        }
        google()
        mavenCentral()
    }
}

3. 添加依赖

application 模块：

groovy

dependencies {
    implementation "com.qcode.cocosstroe:gameloader:1.0.7.20260810"
}

一般不要再手写 libcocos2dx / apk-expansion-zipfile。

宿主环境要求

项	建议
`minSdkVersion`	≥ 19
`compileSdk`	≥ 34
ABI	AAR 含 `armeabi-v7a`、`arm64-v8a`；可用 `ndk.abiFilters` 裁剪
JDK	与宿主 AGP 一致即可（编宿主不需要编 so）

Activity / 权限随 AAR Manifest 合并。权限：INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE。

组件：

org.cocos2dx.gameloader.GameLoaderActivity（exported=true，进程 :cocosgame）
org.cocos2dx.gameloader.CocosGameActivity（exported=false，同进程）

退出游戏会结束 :cocosgame，尽量不影响宿主主进程。

4. 启动游戏

Intent 参数

Key / Action	必填	说明
Action `com.qcode.cocosstroe.action.LOAD_GAME`	推荐	启动 Loader
`zip_url`	是	游戏 zip 下载地址
`game_id`	否	缓存目录名；缺省用 zip 文件名。路径不安全字符会改成 MD5
`max_cached_games`	否	Int，最多保留几个已装游戏（默认 4）
`max_cache_bytes`	否	Long/Int，解压后总大小软上限（默认 512MB）

常量：org.cocos2dx.gameloader.GamePathHolder
（ACTION_LOAD_GAME、EXTRA_ZIP_URL、EXTRA_GAME_ID、EXTRA_MAX_CACHED_GAMES、EXTRA_MAX_CACHE_BYTES）

也可用代码设置缓存上限：

java

GameCacheConfig.setMaxCachedGames(4);                 // ≥ 1
GameCacheConfig.setMaxTotalBytes(512L * 1024 * 1024); // ≥ 1MB

Java / Kotlin

java

import android.content.Intent;
import org.cocos2dx.gameloader.GamePathHolder;

Intent intent = new Intent(GamePathHolder.ACTION_LOAD_GAME);
intent.setPackage(getPackageName()); // 避免隐式 Intent 歧义
intent.putExtra(GamePathHolder.EXTRA_ZIP_URL,
    "http://cdn.release.qcast.cn/JsViewTestCase/cocos2d/测试用游戏包/eatme.zip");
intent.putExtra(GamePathHolder.EXTRA_GAME_ID, "eatme");
startActivity(intent);

或显式组件：

java

Intent intent = new Intent(this, org.cocos2dx.gameloader.GameLoaderActivity.class);
intent.putExtra(GamePathHolder.EXTRA_ZIP_URL, zipUrl);
intent.putExtra(GamePathHolder.EXTRA_GAME_ID, gameId);
startActivity(intent);

adb

YOUR_PACKAGE 换成宿主 applicationId：

bash

adb shell am start -a com.qcode.cocosstroe.action.LOAD_GAME \
  -n YOUR_PACKAGE/org.cocos2dx.gameloader.GameLoaderActivity \
  --es zip_url "http://cdn.release.qcast.cn/JsViewTestCase/cocos2d/测试用游戏包/eatme.zip" \
  --es game_id "eatme"

行为简述

按 game_id 缓存到 files/games/<id>/
已有可用包（含 main.js）则跳过下载
否则下载 → 原子解压 → 打开 CocosGameActivity
失败有错误提示与重试；返回/关闭可取消进行中的任务

默认 LRU：最多 4 个游戏、总缓存约 512MB、尽量保留 ≥64MB 可用空间。

5. 远程游戏包格式

必须是 Creator 2.4.15 Android（jsb-link） 产物，不要带 frameworks/：

bash

cd YourGame/build/jsb-link
zip -r game.zip main.js project.json assets src jsb-adapter \
  -x "*.DS_Store" -x "*__MACOSX*"

要求：

zip 根目录有 main.js
不支持 Web 构建（index.html）
若脚本加密，XXTEA 密钥须与底包一致；否则构建时关掉 encryptJs

6. 与宿主共存注意点

进程：游戏在 :cocosgame，不要假设与主进程共享静态内存
横屏：sensorLandscape
无桌面图标入口：只能由宿主 Intent / adb 拉起
so 体积：按需 abiFilters
okhttp：传递 3.12.13，注意与宿主对齐
ProGuard：保留 Cocos / JNI / 反射相关类

7. JS → Java 反射桥

游戏脚本可通过 jsb.reflection.callStaticMethod 调用 Java public static 方法。
底座还会注入 window.AppBridge，兼容小米渠道 AppBridge.call(json)。

7.1 `jsb.reflection.callStaticMethod`

javascript

jsb.reflection.callStaticMethod(
  "org/cocos2dx/gameloader/AppBridge",  // 类名用 /，不要用 .
  "call",
  "(Ljava/lang/String;)V",
  jsonStr
);

Java 类型	JNI
`void`	`V`
`boolean`	`Z`
`int`	`I`
`float`	`F`
`String`	`Ljava/lang/String;`

只能调 public static；混淆时需 keep。

7.2 `window.AppBridge`（底座已注入）

javascript

window.AppBridge.call(JSON.stringify({
  action: "exitGame",
  data: {},
  callbackId: "cb_1"
}));

action	行为
`exitGame`	finish 当前游戏 Activity（`:cocosgame`）
其它	仅 Log

扩展：在 Java AppBridge.call 里按 action 分支即可。

7.3 直接反射示例

javascript

var ret = jsb.reflection.callStaticMethod(
  "org/cocos2dx/gameloader/GameLoaderActivity",
  "pingFromJs",
  "(Ljava/lang/String;)Ljava/lang/String;",
  "hello"
);
// ret === "pong:hello"

反射进入的是 游戏进程，与大厅通信请用跨进程方案。

8. 自检清单

Nexus 能解析 com.qcode.cocosstroe:gameloader:...
minSdk ≥ 19，abiFilters 覆盖目标设备
setPackage(getPackageName()) 或显式 Activity 启动
zip_url 可访问，包内根目录有 main.js
logcat 可见下载或缓存命中，再进 CocosGameActivity

引导

Android 集成

如何启动小程序

Android-JS API

插件开发方案

高级功能

常见问题

鸿蒙（OpenHarmony）集成

Cocos 游戏加载底座

Cocos gameloader — Maven 集成

1. 坐标与产物

2. 仓库配置

3. 添加依赖

宿主环境要求

4. 启动游戏

Intent 参数

Java / Kotlin

adb

行为简述

5. 远程游戏包格式

6. 与宿主共存注意点

7. JS → Java 反射桥

7.1 `jsb.reflection.callStaticMethod`

7.2 `window.AppBridge`（底座已注入）

7.3 直接反射示例

8. 自检清单

Cocos gameloader — Maven 集成 ​

1. 坐标与产物 ​

2. 仓库配置 ​

3. 添加依赖 ​

宿主环境要求 ​

4. 启动游戏 ​

Intent 参数 ​

Java / Kotlin ​

adb ​

行为简述 ​

5. 远程游戏包格式 ​

6. 与宿主共存注意点 ​

7. JS → Java 反射桥 ​

7.1 jsb.reflection.callStaticMethod ​

7.2 window.AppBridge（底座已注入） ​

7.3 直接反射示例 ​

8. 自检清单 ​

Cocos gameloader — Maven 集成

1. 坐标与产物

2. 仓库配置

3. 添加依赖

宿主环境要求

4. 启动游戏

Intent 参数

Java / Kotlin

adb

行为简述

5. 远程游戏包格式

6. 与宿主共存注意点

7. JS → Java 反射桥

7.1 `jsb.reflection.callStaticMethod`

7.2 `window.AppBridge`（底座已注入）

7.3 直接反射示例

8. 自检清单