SDK 架构

Migo 是可嵌入的 Canvas/WebGL 小游戏运行容器。migo.* 是引擎安装给内容的唯一能力表面；微信和 Web 适配器（例如 migo-wx-adapter、migo-web-adapter）属于独立仓库，不是引擎内置模块。Migo 没有 DOM 或 CSS，也不应被描述为通用 WebView 替代品。

组件拓扑

flowchart TB
  Bundle[小游戏 bundle] --> Adapter[独立适配器（可选）]
  Adapter --> Boundary[migo.* capability boundary]
  Boundary --> Core[Rust core]
  Core --> V8[V8 JavaScript runtime]
  Core --> Render[Skia / Canvas / WebGL]
  Host[宿主 App] <--> SDK[C ABI（Android 之上有语言 facade）]
  SDK <--> Core
  Host --> Services[surface · input · storage · network · ads]

文字说明

小游戏 bundle 只通过 migo.* 能力边界访问运行时能力；可选的独立适配器位于引擎之外。
Rust core 编排 V8 JavaScript runtime 与 Skia 渲染后端，输出 Canvas/WebGL 内容。
宿主 App 通过 C ABI 创建和管理会话 — 这是四个平台唯一共有的事实接口;Android 侧惯用的 Java facade(MigoRuntime/MigoGameView)只是这层 ABI 之上的语言包装。surface、input、storage、network、ads 等服务由宿主自行提供。
Migo 不提供 DOM、CSS、页面布局或浏览器文档对象模型。

会话生命周期

图上只写函数名；完整签名按所属头文件去 Session、Surface 各页查。

初始化

sequenceDiagram
  participant Host as 宿主 App
  participant ABI as Migo C ABI
  participant Engine as Engine
  participant Session as Session
  participant Content as Bundle
  Host->>ABI: migo_engine_create
  ABI->>Engine: 创建引擎
  Host->>ABI: migo_session_create
  ABI->>Session: 创建会话
  Host->>ABI: migo_session_set_host_callbacks
  Host->>ABI: migo_session_attach_surface
  Host->>ABI: migo_session_load_content
  ABI->>Content: 加载 bundle

文字说明

宿主先调用 migo_engine_create，再调用 migo_session_create 获取会话句柄。
会话建立后安装 migo_session_set_host_callbacks，再用 migo_session_attach_surface 提供渲染目标。
migo_session_load_content 加载内容 bundle，只此一次（二次调用返回 MIGO_ERROR_INVALID_STATE）。

每帧与输入

sequenceDiagram
  participant Host as 宿主 App
  participant ABI as Migo C ABI
  participant Session as Session
  participant Content as Bundle
  loop 每帧
    Host->>ABI: migo_session_notify_vsync
    ABI->>Session: 推进帧与渲染
    Session-->>Host: host callbacks / frame output
  end
  Host->>ABI: migo_session_send_touch
  ABI->>Content: 转发输入

文字说明

宿主按显示系统节奏调用 migo_session_notify_vsync 推进帧（仅在收到 on_request_frame 后）。
触摸事件通过 migo_session_send_touch 进入内容输入流；其他输入类型使用 input.h 中对应的 migo_session_send_* 接口。

释放

sequenceDiagram
  participant Host as 宿主 App
  participant ABI as Migo C ABI
  participant Engine as Engine
  participant Session as Session
  Host->>ABI: migo_surface_begin_detach
  Host->>ABI: migo_surface_release_query
  ABI-->>Host: 查询释放状态
  Host->>ABI: migo_session_destroy
  ABI->>Session: 销毁会话
  Host->>ABI: migo_engine_destroy
  ABI->>Engine: 销毁引擎

文字说明

surface 丢失时先调用 migo_surface_begin_detach，再用 migo_surface_release_query 等待释放状态。
释放完成后按拥有关系销毁会话和引擎；销毁返回 MIGO_OK 后句柄立即失效。

平台边界

Android、Linux、Windows：使用 V8；宿主分别通过 Android facade 或可链接的 C ABI 运行时接入。
HarmonyOS NEXT：由于 HarmonyOS 5.0.0(12) 起匿名内存执行权限限制，Migo 使用 jitless 模式运行 V8；不要宣称 NEXT 上的 JIT 性能。
Apple：外部 frame 会话使用 CAMetalLayer；实现尚未完成生产发布验证，因此不应据此作出生产性能声明。

Migo 的构建流程和平台依赖见仓库的 BUILD.md。