Cocos gameloader — Maven 集成

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

接入方只需依赖一个坐标，其余依赖由 POM 传递拉齐；游戏资源不需要打进宿主 APK，运行时从远程 zip 下载。

想先看效果，可装现成底座 APK 跑一遍：快速演示。

1. 坐标与产物

坐标	版本	说明
`com.qcode.cocosstore:gameloader`	`1.0.29.20260922`	主库：游戏下载与缓存、Cocos 引擎启动
`com.qcode.cocosstore:libcocos2dx`	`2.4.15`	Cocos Java 桥（传递）
`com.qcode.cocosstore:apk-expansion-zipfile`	`1.0`	Expansion 辅助库（传递）
`com.squareup.okhttp3:okhttp`	`3.12.13`	网络下载（传递）

版本号以 Nexus maven-releases 实际发布为准，接入时建议取该仓库当前最新版。

2. 仓库配置

正式产物发布在公司 Nexus：

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.cocosstore:gameloader:1.0.29.20260922"
}

libcocos2dx / apk-expansion-zipfile / okhttp 会由 POM 自动引入，不需要手写。

宿主环境要求

项	要求
`minSdkVersion`	≥ 18（可覆盖 Android 4.3 及以上的偏低机型）
`compileSdk`	≥ 34
ABI	AAR 含 `armeabi-v7a`、`arm64-v8a`，用 `ndk.abiFilters` 按目标设备裁剪
JDK	与宿主 AGP 保持一致即可（接入方不需要编译 native 代码）

注意：宿主的 minSdk 不能低于 SDK 及其依赖（libcocos2dx、apk-expansion-zipfile）的 minSdk，否则构建时会在 Manifest 合并阶段报错。若工程此前已接入过旧版本，改 minSdk 后建议执行一次 ./gradlew --refresh-dependencies，避免用到本地缓存的旧依赖。

合并进来的内容

权限（随 AAR Manifest 合并，无需手动声明）：INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE。

组件：AAR 提供一个 对外入口 Activity，宿主只需拉起它；下载、缓存、换游戏等逻辑都在 SDK 内部完成，宿主无需注册或调用任何 Service。

4. 启动游戏

Intent 参数

Key / Action	必填	说明
Action `com.qcode.cocosstore.action.LOAD_GAME`	推荐	启动游戏
`zip_url`	是	游戏 zip 下载地址（http / https）
`game_id`	否	游戏标识，同时作为本地缓存目录名；缺省用 zip 文件名
`max_cached_games`	否	Int，最多保留几个已装游戏（默认 4）
`max_cache_bytes`	否	解压后缓存总大小上限，字节（默认 512MB）

game_id 请使用稳定且唯一的英文标识（建议用游戏的包名或版本无关的业务 id）。同一个 game_id 再次启动会直接命中缓存；换了游戏内容但 game_id 不变，本地不会更新。

后两个缓存配额是运行期设置，不是单次启动参数：带上就生效并持续保留，不带则沿用上次的值（不会自动回到默认）。

Java / Kotlin

java

Intent intent = new Intent(GamePathHolder.ACTION_LOAD_GAME);
// 建议 setPackage，避免多应用声明同一 action 时产生歧义
intent.setPackage(getPackageName());
intent.putExtra(GamePathHolder.EXTRA_ZIP_URL, zipUrl);
intent.putExtra(GamePathHolder.EXTRA_GAME_ID, gameId);
startActivity(intent);

也可以直接指定组件启动：

java

Intent intent = new Intent(this, org.cocos2dx.gameloader.CocosGameActivity.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.cocosstore.action.LOAD_GAME \
  -n YOUR_PACKAGE/org.cocos2dx.gameloader.CocosGameActivity \
  --es zip_url "http://cdn.release.qcast.cn/JsViewTestCase/cocos2d/测试用游戏包/eatme.zip" \
  --es game_id "eatme"

运行行为

首次启动：显示加载态 → 下载并解压到 files/games/<game_id>/ → 进入游戏
已完整缓存过：跳过下载，直接进入游戏
下载过程边下边解，中断后重试；已缓存完成的游戏不会被中途的任务破坏
失败会给出提示并允许重试；退出游戏可取消进行中的下载
一次只运行一个游戏：启动另一个 game_id 时，SDK 会先结束当前游戏，再启动新游戏，宿主不需要自己处理

首次启动速度：SDK 会先取运行必需的资源让游戏尽快显示，剩余资源在后台补齐。这依赖游戏服务器支持 Range（详见第 7 节）。

默认缓存策略：最多保留 4 个游戏、总大小约 512MB，按最近使用时间淘汰最久未用的游戏。

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. 与宿主共存注意点

独立进程：游戏运行在独立进程中，与宿主主进程隔离，不要假设两者能共享静态数据；退出或切换游戏时该进程会结束，宿主主进程不受影响
横屏：游戏页固定为横屏
无桌面图标：SDK 不提供 launcher 入口，只能由宿主 Intent / adb 拉起
APK 体积：so 较大，务必用 abiFilters 只保留目标设备 ABI
okhttp：传递版本为 3.12.13，若宿主已有其它版本请确认兼容性
混淆：宿主开启混淆时，不要混淆 SDK 与 Cocos 相关的类（AAR 已附带 consumer 规则，如宿主有自定义 keep 规则，注意不要移除）

7. 游戏服务器要求

游戏 zip 建议放在支持 HTTP Range 的静态服务器 / CDN 上（阿里云 OSS、nginx 静态文件均默认支持）。

情况	效果
支持 Range（推荐）	首次启动明显更快：SDK 先取运行必需的资源先进入游戏，其余后台补齐
不支持 Range	功能完全正常，退化为下载整包后再进入游戏，首启较慢
支持 ETag	建议开启，可避免更新游戏包后新旧内容混用
使用 `python -m http.server` 之类的简易服务	仅供本地调试，不支持 Range，无法体现加速效果

8. JS ↔ Android 通信

游戏脚本（Creator JSB）可通过 Cocos 自带的 jsb.reflection.callStaticMethod 调用 Android 侧的 public static 方法，底座已封装好一个通用入口。

`window.AppBridge`（已注入，推荐）

引擎启动时会注入全局对象 window.AppBridge，兼容小米渠道常用的调用方式：

javascript

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

已支持的 action：

action	行为
`exitGame`	结束当前游戏并退出游戏页
其它	仅记录日志，不会抛错或崩溃

宿主或游戏需要更多能力（支付、登录、上报等）时，在 action 上扩展即可。

直接反射调用

也可以绕过封装，直接调用 Android 侧提供的静态方法：

javascript

var ret = jsb.reflection.callStaticMethod(
  "org/cocos2dx/gameloader/AppBridge",  // 类名用 / 分隔
  "call",                               // 方法名，须为 public static
  "(Ljava/lang/String;)V",              // 参数与返回值签名
  jsonStr
);

需要注意：只能调用 public static 方法；方法所在类必须在运行期可用；宿主若开启混淆，被调用的类与方法需要 keep。

与宿主大厅通信时，请使用 Intent / Binder 等跨进程方式，不要依赖静态变量（游戏运行在独立进程）。

9. 自检清单

Nexus 能解析 com.qcode.cocosstore:gameloader
minSdk ≥ 18，abiFilters 覆盖目标设备
用 setPackage(getPackageName()) 或显式组件启动
zip_url 可访问，且 zip 根目录含 main.js
游戏服务器支持 Range / ETag（推荐）
真机日志中能看到下载或缓存命中，随后进入游戏画面

引导

Android 集成

如何启动小程序

Android-JS API

插件开发方案

高级功能

常见问题

鸿蒙（OpenHarmony）集成

Cocos 游戏加载底座

Cocos gameloader — Maven 集成

1. 坐标与产物

2. 仓库配置

3. 添加依赖

宿主环境要求

合并进来的内容

4. 启动游戏

Intent 参数

Java / Kotlin

adb

运行行为

5. 远程游戏包格式

6. 与宿主共存注意点

7. 游戏服务器要求

8. JS ↔ Android 通信

`window.AppBridge`（已注入，推荐）

直接反射调用

9. 自检清单

Cocos gameloader — Maven 集成 ​

1. 坐标与产物 ​

2. 仓库配置 ​

3. 添加依赖 ​

宿主环境要求 ​

合并进来的内容 ​

4. 启动游戏 ​

Intent 参数 ​

Java / Kotlin ​

adb ​

运行行为 ​

5. 远程游戏包格式 ​

6. 与宿主共存注意点 ​

7. 游戏服务器要求 ​

8. JS ↔ Android 通信 ​

window.AppBridge（已注入，推荐） ​

直接反射调用 ​

9. 自检清单 ​

Cocos gameloader — Maven 集成

1. 坐标与产物

2. 仓库配置

3. 添加依赖

宿主环境要求

合并进来的内容

4. 启动游戏

Intent 参数

Java / Kotlin

adb

运行行为

5. 远程游戏包格式

6. 与宿主共存注意点

7. 游戏服务器要求

8. JS ↔ Android 通信

`window.AppBridge`（已注入，推荐）

直接反射调用

9. 自检清单