android-frame/frame/game/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

模块概述

frame/game 是游戏SDK封装或小游戏容器集成模块，主要提供了Android原生应用与基于Cocos2d-x引擎的游戏之间的双向通信桥梁。

核心架构

主要组件

IGameApp (游戏应用接口)

• 核心工厂方法：IGameApp.loadGame(gameAppInfo, isGameInit)
• 提供双向通信能力：callGame() 调用游戏方法，addNativeMethod() 注册原生方法
• 支持串行/并行执行模式和回调超时机制

GameAppImpl (游戏应用实现)

• 基于 BaseFrame<IListener> 和 JsbBridge.ICallback 实现
• 管理原生方法注册表 (methodMap) 和回调映射 (callbackMap)
• 处理JSON序列化/反序列化和错误码管理

IGameEngine (游戏引擎接口)

• 继承自 IGameViewModel，提供游戏引擎层面的抽象
• enterGame() 方法兼容引擎延迟销毁问题

GameNativeBridge (原生桥接)

• 提供JNI接口：onCreateNative(activity, gamePath)
• 连接原生代码与C++游戏引擎

Cocos服务集成

• SDKWrapper 提供Cocos2d-x引擎的SDK生命周期管理
• 支持插件式SDK加载 (通过 service.json 配置)

数据流架构

Android原生应用 ↔ GameAppImpl ↔ JsbBridge ↔ Cocos2d-x游戏
                     ↕
               GameNativeBridge (JNI)

通信机制

1. 原生调用游戏：callGame(methodName, data, callback) → JsbBridge → 游戏JS/C++
2. 游戏调用原生：游戏JS/C++ → JsbBridge → onScript() → 注册的原生方法
3. 数据格式：统一使用JSON进行序列化，支持泛型类型推断

错误处理

• 定义完整的 GameErrorCode 枚举 (10001-10011)
• 回调超时机制 (默认10秒)
• JSON解析错误处理
• 方法不存在、类型错误等异常处理

依赖关系

框架依赖

• frame/base：基础框架 (必需)
• frame/mvvm：MVVM架构支持
• frame/coroutine：协程工具
• frame/log：日志系统
• frame/data：数据转换工具
• frame/util：通用工具

外部依赖

• external/libcocos2dx：Cocos2d-x引擎集成

关键文件说明

• IGameApp.kt:10 - 游戏应用工厂方法入口
• GameAppImpl.kt:90-94 - 核心游戏通信逻辑
• GameAppImpl.kt:111-205 - 游戏回调处理机制
  
• GameData.kt:74-87 - 错误码定义
• SDKWrapper.java:100-106 - Cocos SDK初始化逻辑

开发规范

1. 方法注册：使用 addNativeMethod() 注册原生方法前，确保实现 IGameNativeMethod<T,R> 接口
2. 回调处理：游戏调用原生方法时，必须通过 IGameNativeCallback 返回结果
3. 序列化：数据传输统一使用JSON格式，复杂对象需要定义相应的数据类
4. 错误处理：使用预定义的 GameErrorCode，避免自定义错误码
5. 线程安全：游戏通信涉及多线程，注意使用 ConcurrentHashMap 等线程安全容器