games-development-ai/.agents/skills/runtime-and-multichannel.md

name, description

name	description
runtime-and-multichannel	当开发/调试 runtime 编译与包版本化交付、WanxiangGameSDK 注入与降级、iframe 沙箱三容器预加载、或微信/抖音/快手多渠道导出时使用:渲染层 LittleJS 增强发行版、SDK 两层、沙箱安全边界与微信格式导出枢纽。

运行时、Game SDK 与多渠道导出手册（runtime-and-multichannel）

蒸馏来源：docs/architecture/架构/README.md（§3.4 Game SDK / §4.2 运行时三容器 / §6.6 运行时与导出选型）、docs/architecture/架构/13模块.md（runtime 模块 T-RT-* 技术功能）、docs/architecture/架构/README.md（§2 模块地图 / §10.4 LayaAir CLI）。 适用：开发/调试 runtime 模块、WanxiangGameSDK、多渠道（微信/抖音/快手）小游戏导出。 配套：SDK 降级铁律与沙箱安全红线见 ../rules/security-and-reliability.md；工程规范见 ../rules/engineering-conventions.md；架构全景见 ../knowledge/product-and-architecture.md；上游生成见 ./agentic-amodel-generation.md；契约见 ./contract-first-development.md。 ⚠️ 状态升级（2026-06-12 终裁，取代 2026-06-11 待 spike 表述）：本手册「自研 Canvas Runtime(<15KB)」相关段落=1.x 历史口径，渲染层已改判。现行裁决：

• Tier1 渲染层 = LittleJS 增强发行版 + Runner v2（2026-06-12 创始人终裁，spike 85/82；Phaser 竞标落选）；「自研轻量 Canvas Runtime / <15KB 体积门」废除（15KB 系 srcdoc 内联架构衍生约束，前提已失效），改三层约束框架（SLO@千元机+4G P75 / B1 gz≤350KB·raw≤1.5MB / 工程增强层）。
• 模板 = LittleJS 能力插件/二次开发件（玩法模板层废除）；粒子/物理/后处理三插件=引擎能力包装层（裁决①2026-06-12），collision/手感=引擎缺件维持自研。
• 沙箱 / SDK Core 注入 / 三容器预加载 / 多渠道导出枢纽章节不受影响，仍现行有效。 单一事实源：../knowledge/tech-decisions.md §1.1 + git show 6d2f8789^:docs/agent-specs/_archive/2026-06-11-T1引擎终裁包.md（已随 _archive 清理删除、git 定位）。下文凡「自研 Canvas<15KB / OpenGame 生成」字样均按本横幅改读。 ⚠️ 纠偏（2026-07-05）：① 编译输入口径改真——runtime 编译输入 = 上游 src/ 多文件源工程，产出 engineBundle（iife、全局 __GameBundle 承重）；gameConfig 降为模板玩法参数占位（contracts/game-package.schema.json 可核）。② runtime service 真目录 = service/build/ service/pkg/ service/session/（旧稿 service/compiler/、service/package/ 已不存在）。③ §6 多渠道代码件系（service/conversion/、WechatAdapter/DouyinAdapter/KuaishouAdapter.java）规划中·未实现——全仓无此源文件，微信格式枢纽策略叙述仍有效。

---

目标

把上游 src/ 多文件源工程编译为可运行 Web 包（engineBundle iife 承重、gameConfig 降为模板玩法参数占位）并版本化交付，注入 WanxiangGameSDK，在 iframe 沙箱中安全运行（三容器预加载），并支持向微信/抖音/快手等小游戏渠道静态导出。产出后游戏流可即点即玩、可分发到外部渠道。

前置

• OSS（本地 MinIO）+ CDN 可用。Cocos（仅留 3D / 渠道导出、人在环、非分档轴）官方一键导出微信包；LittleJS 线（自研 Canvas）渠道 adapter 走 W-CH-α 对比竞标（LittleJS+自研 adapter vs Cocos 导出，HJ-CH-001）（见 ../knowledge/tech-decisions.md §1.1）。
• SDK Core 体积达标（< 8KB 压缩）；上游 aigc 产出的 GamePackage 符合 game-package.schema.json 契约。

---

1. runtime 模块职责

职责	说明
src/ 源工程 → 可运行 Web 包编译	service/build/：src/ 源工程 + assets → engineBundle（iife 承重）web bundle
Manifest 生成	runtimeVersion / configUrl / assetList / hash / preloadPolicy / bundleSize
包存储版本化	service/pkg/：checksum(sha256) + CDN，路径 /games/{gameId}/versions/{versionId}/
预览交付端点	controller/app/runtime/：按版本返回 manifest + 资源 URL（真路径 GET /app-api/runtime/package/{versionId}?scene=preview；预览为 scene 参数、无独立 /preview 路径）
多渠道转换	service/conversion/（规划中·未实现）：以导出微信小游戏格式包为枢纽 → 抖音(自有接口)/快手(微信格式兼容转换)；渠道 adapter 走 W-CH-α 竞标（Cocos 仅留 3D / 渠道导出、人在环，见 §6 与顶部横幅）

渲染层：自研轻量 Canvas Runtime（< 15KB） → LittleJS 增强发行版 + Runner v2（2026-06-12 终裁，见顶部横幅；15KB 红线废除），iframe sandbox + SDK Core 注入，平台完全控制沙箱（沙箱/SDK 注入语义不变；技术决策版 §6.6 的"自研薄壳"结论已被引擎选型取代）。

本手册聚焦 Tier1（极轻量 2D，游戏流）。分层运行时见 ../knowledge/tech-decisions.md §1.1（正交两轴：AI 参与深度 Tier0/1/2 与引擎按表现复杂度选 LittleJS/Phaser 是两根正交轴、引擎不是分档轴；Cocos 仅留 3D / 渠道导出轴、编辑器 + 人在环，进不了自治生成轨）。

---

2. 三容器预加载策略

参考抖音短视频预加载，只保留前/当/后三个容器（技术决策版 §4.2，详见 Doc B runtime 模块）：

[Container N-1]   [Container N]   [Container N+1]
   (销毁中)         (当前播放)      (预加载完成)

• 当前游戏播放时，预加载下一款 manifest + 关键资源。
• 加载超时则自动跳过下一款 + 记录 game_load_failed + 错误上报降权（详见 Doc B runtime 模块）。
• 上滑切换：销毁 N-1，N+1 转为当前，再预加载新的 N+1。

---

3. 安全边界

项	配置	出处
iframe sandbox	sandbox="allow-scripts allow-same-origin"	技术决策版 §4.2
CSP	script-src 'self'; connect-src 'none'（游戏内无网络请求）	技术决策版 §4.2
postMessage 校验	来源（origin 白名单）+ schema 双校验，防伪造	技术决策版 §4.2，Doc B runtime 模块
资源大小	总资源 ≤ 10MB，首屏 ≤ 2MB，超限编译失败	技术决策版 §4.2，Doc B runtime 模块

游戏 iframe 禁止网络，所以广告/支付/社交都在宿主侧 iframe 外渲染（见第 4 节）。沙箱逃逸是极高危风险，检测到异常立即销毁 iframe（技术决策版 §8 风险 3）。详细红线见 ../rules/security-and-reliability.md。

---

4. WanxiangGameSDK

SDK 是平台能力注入游戏的唯一通道——没有 SDK，平台就是静态文件托管（技术决策版 §3.4）。分两层：

Core（内联 < 8KB，游戏启动时加载，异步不阻塞）
├── Lifecycle    ready/started/paused/resumed/completed/error + onPause/onResume
├── EventBus     SDK ↔ 宿主 postMessage 通信
├── Telemetry    事件批量上报（10 条 / 5s flush，sendBeacon 兜底）
└── ErrorTrack   onerror + unhandledrejection 捕获、去重、不中断游戏

Plugin（按需懒加载，首次调用对应 API 时加载，不影响首屏）
├── Ad           激励视频 / 插屏 / Banner（宿主侧渲染）
├── Pay          内购 / 打赏触发（宿主侧弹支付 UI）
├── Social       排行榜 / 好友 / 邀请 / 分享（宿主代理请求）
└── Storage      云存档 / 进度（失败回退 localStorage）

SDK ↔ 宿主 postMessage 协议（消息 type）：init / lifecycle / telemetry / ad / pay / social / storage。

关键决策（技术决策版 §3.4）：

• 广告与支付在宿主侧（iframe 外）渲染——因为它们要网络权限，而游戏沙箱无网络。
• 事件 SDK 内缓冲 10 条 / 5s flush，减少 postMessage 频率、不影响帧率。
• 降级铁律：Plugin 层全部 try-catch 包裹，异常不向上抛，游戏主循环（requestAnimationFrame）永不被 SDK 阻塞。完整降级表见 ../rules/security-and-reliability.md。

---

5. SDK 与 runtime 的关系

runtime 编译 GamePackage 时：
1. 把 SDK Core 代码内联进游戏 entry.js 头部
2. 源工程声明所需 Plugin（ad / pay / social / storage）；gameConfig 降为模板玩法参数占位
3. manifest.json 记录 SDK 版本号
4. 宿主据 manifest 决定加载哪些 Plugin chunk

游戏代码不直接引用广告联盟/支付 SDK——只通过 sdk.ad.showRewarded() 等抽象 API 触发，具体实现对游戏透明、由宿主在 iframe 外管理（技术决策版 §3.4）。

---

6. 多渠道导出（构建期静态转换）

构建期静态转换（非运行时动态适配），导出可异步离线进行、不影响实时预览（技术决策版 §6.6）。

导出枢纽 = 微信小游戏格式包：

渠道	导出路径
微信	引擎/壳导出微信小游戏包（官方格式）
抖音	抖音自有导出接口
快手	无专用导出接口 → 快手开发者工具"微信格式兼容转换"（基础 API 与微信一致，开放 API 需快手专属代码）

快手导出渠道清单不含 LayaAir CLI 路线：LayaAir 官方平台清单无快手，快手统一走"微信格式包兼容转换"。"统一工具链"实质 = 统一产出微信格式包，再分发抖音/快手。详见 ../knowledge/tech-decisions.md §1.1。

导出工具：Cocos（仅留 3D / 渠道导出、人在环）官方一键导出微信包，LittleJS 线（自研 Canvas）渠道 adapter 走 W-CH-α 竞标（见顶部横幅）。Java（runtime service/conversion/，规划中·未实现）设计上统一以 ProcessBuilder 调用对应工具 → 异步等待进程 → 产物上传 OSS。

渠道适配器（规划中·未实现；开发团队版 §2.1 设计，下列 Java 文件全仓尚不存在）各自处理尺寸 / 资质 / 文案 / 违禁词：

• WechatAdapter.java（规划中） — 微信小游戏适配规则
• DouyinAdapter.java（规划中） — 抖音小游戏适配规则
• KuaishouAdapter.java（规划中） — 快手适配（微信格式 → 快手兼容转换）

外部进程调用要按 ../rules/security-and-reliability.md 处理超时/失败/重试/产物校验。

---

7. 资源优化

手段	说明	出处
hash 命名长期缓存	hash 文件名启用 CDN 永久缓存	Doc B runtime 模块
WebP/AVIF 转换	素材压缩 + 尺寸裁剪降首屏	Doc B runtime 模块
CDN 发布刷新	发布时刷新需更新的 HTML/Manifest CDN 缓存	Doc B runtime 模块
低端设备降级	限制粒子/音频预加载，帧率锁 30fps	Doc B runtime 模块

---

8. 常见坑

坑	排查 / 应对
postMessage 收不到	查 iframe origin 白名单是否放行 + Console 报错（开发团队版 §9）；确认 schema 校验未误拦
DevTool import 导出包看着对	渠道包仍需真机验证（开发者工具 import 不等于真机通过）
小游戏导出拖慢预览	导出可异步离线进行，与实时预览解耦，不影响游戏流加载（技术决策版 §6.6）
首屏超 2MB / 总包超 10MB	编译门禁直接阻断 + 给优化建议；走 WebP/AVIF + 音频懒加载
三容器内存涨	严格只保留前/当/后三容器，及时销毁 N-1（技术决策版 §4.2）
加载卡死无兜底	加载超时 5s 自动跳过 + 错误记录 + 降权（技术决策版 §7.2）