loadPackage

加载游戏包

loadPackage 方法用于将特定的游戏资源包（Package）加载到已经初始化好的运行时环境中。它是游戏启动链路中的“资源装载”阶段，负责解析游戏包的目录结构、校验配置文件，并为后续的脚本执行做好资源映射准备。

该接口返回一个 ISUDRTFSTAPP 句柄，允许开发者对加载过程进行细粒度的状态管理（如监控解压进度或手动干预加载流）。

---

方法声明

/**
 * 加载游戏包
 *
 * @param model   加载游戏包的参数模型（包含游戏包路径、ID 等）
 * @param fsmGame 加载过程的状态机回调（用于监听加载各阶段状态）
 * @return ISUDRTFSTAPP 加载操作句柄，可用于管理加载任务
 */
ISUDRTFSTAPP loadPackage(
    SUDRTLoadGameParamModel model, 
    ISUDRTFSMGame fsmGame
);

---

参数说明

1. SUDRTLoadGameParamModel (加载模型)

该模型承载了游戏包的物理位置和元数据。常用配置项包括：

• gameId: 游戏的唯一标识。
• gamePkgPath: 游戏资源包在本地磁盘的绝对路径。
• extraConfig: 额外的业务自定义配置（Bundle 类型）。

2. ISUDRTFSMGame (状态机回调)

这是一个基于状态机（FSM）设计的回调接口，开发者可以通过它感知加载的每一个微观阶段：

• onLoading: 正在解析资源。
• onLoaded: 资源解析完成，准备进入运行环境。
• onError: 加载过程中出现异常（如配置文件 app.json 缺失或损坏）。

---

运行行为

1. 包结构校验：SDK 会检查 gamePkgPath 指向的路径，验证其是否包含合法的游戏入口文件（通常是 app.json 或 index.js）。
2. 资源映射：建立虚拟文件系统映射，使 JS 环境中通过相对路径访问资源时能正确指向本地物理路径。
3. 分包预处理：如果游戏包含子包（Sub-packages），此接口会初始化分包加载管理器。
4. 返回句柄：返回的 ISUDRTFSTAPP 实例代表了当前“加载中”的游戏应用对象，通过它可以触发后续的“运行（Run）”操作。

---

代码示例

// 1. 构造加载参数
SUDRTLoadGameParamModel model = new SUDRTLoadGameParamModel();
model.gameId = "game_id_888";
model.gamePkgPath = "/sdcard/Android/data/com.app/files/games/game_888/";

// 2. 执行加载并监听状态
ISUDRTFSTAPP appTask = runtime.loadPackage(model, new ISUDRTFSMGame() {
    @Override
    public void onGameStateChange(int state, Bundle data) {
        if (state == ISUDRTFSMGame.STATE_LOADED) {
            Log.i("SUDOP", "Package loaded successfully!");
        }
    }

    @Override
    public void onError(int code, String msg) {
        Log.e("SUDOP", "Package load failed: " + msg);
    }
});

---

注意事项

• 路径格式：确保 gamePkgPath 传入的是解压后的目录路径。如果还是 .zip 文件，应先通过 ISUDRTGamePackageManager 进行解压。
• 状态互斥：一个 Runtime 实例通常只能同时执行一个主包的 loadPackage 操作。
• 资源锁：在加载期间，请勿对该目录下的文件进行重命名或移动操作，否则可能导致渲染异常。

---