kadou-game-sdk 1.0.2 → 1.0.3

package/README.md

@@ -1,878 +1,73 @@
-# kadou-game-sdk
-
-Kadou 游戏通信 SDK，用于宿主页面与 iframe 游戏页面之间的通信、生命周期管理、主题同步，以及开始页 / 结束页等覆盖层页面的统一控制。
-
-适用于以下场景：
-
-- Vue / React / 原生 HTML 宿主页中嵌入 iframe 游戏
-- 线上配置加载 / 离线本地 JSON 加载的统一接入
-- 游戏页面与宿主页面通过 `postMessage` 通信
-- 宿主页统一控制主题、开始页、结束页、游戏状态
-- 不同技术栈游戏统一接入（HTML / Canvas / Vue / Construct 等）
-
----
-
-## 目录
-
-- [特性](#特性)
-- [安装](#安装)
-- [包导出说明](#包导出说明)
-- [核心概念](#核心概念)
-- [快速开始](#快速开始)
-- [Host 宿主页接入](#host-宿主页接入)
-- [Game 游戏页接入](#game-游戏页接入)
-- [API 文档](#api-文档)
-  - [GameRuntime](#gameruntime)
-  - [实例方法](#实例方法)
-  - [实例事件](#实例事件)
-  - [状态字段](#状态字段)
-- [消息流转时序](#消息流转时序)
----
-
-## 特性
-
-- 统一封装 iframe 与宿主页的 `postMessage` 通信
-- 提供事件机制，方便监听游戏生命周期
-- 管理 SDK / Game 状态
-- 支持开始页、结束页渲染
-- 支持主题同步与动态主题加载
-- 支持心跳检测
-- 支持题目流程、答题流程、排行榜、音量等扩展能力
-- 支持 ESM / CJS / UMD
-- 兼容老项目，构建目标包含 IE11
-
----
-
-## 安装
-
-### npm
-
-```bash
-npm install kadou-game-sdk
-```
-
-### yarn
-
-```bash
-yarn add kadou-game-sdk
-```
-
-### pnpm
-
-```bash
-pnpm add kadou-game-sdk
-```
-
----
-
-## 包导出说明
-
-本包默认提供以下产物：
-
-- `dist/kadou-game-sdk.esm.js`
-- `dist/kadou-game-sdk.cjs`
-- `dist/kadou-game-sdk.umd.js`
-- `dist/kadou-game-sdk.umd.min.js`
-
-### 包信息
-
-- 包名：`kadou-game-sdk`
-- `main`: `dist/kadou-game-sdk.cjs`
-- `module`: `dist/kadou-game-sdk.esm.js`
-- `browser`: `dist/kadou-game-sdk.umd.js`
-- `unpkg/jsdelivr`: `dist/kadou-game-sdk.umd.min.js`
-
-### UMD 全局变量
-
-浏览器通过 script 标签引入后，可通过全局变量访问：
-
-```js
-window.KadouGameSDK
-```
-
----
-
-## 核心概念
-
-SDK 中有两个核心角色：
-
-### 1. host
-
-宿主页面，通常是你的 Vue 壳、React 壳、官网页面、企业平台页面。
-
-职责通常包括：
-
-- 创建 iframe
-- 初始化 SDK
-- 把 iframe 的 `contentWindow` 作为通信目标
-- 拉取游戏配置
-- 拉取主题配置
-- 通知游戏加载、开始、结束、配置变更等
-- 接收游戏回传的结果、答题数据、错误信息等
-
-### 2. game
-
-真正运行游戏的 iframe 页面。
-
-职责通常包括：
-
-- 初始化 SDK
-- 与宿主页通信
-- 接收主题
-- 接收开始页 / 结束页显示指令
-- 在游戏开始、结束、答题时向宿主上报状态
-- 渲染覆盖层 UI（开始页、结束页）
-
----
-
-## 快速开始
-
-### ESM 方式
-
-```js
-import { GameRuntime, MESSAGE_TYPES } from 'kadou-game-sdk';
-
-const runtime = new GameRuntime({
-  role: 'host',
-  debug: true
-});
-
-runtime.init();
-
-runtime.on('game:ready', function () {
-  console.log('游戏已准备完成');
-});
-```
-
-### CommonJS 方式
-
-```js
-const sdk = require('kadou-game-sdk');
-const GameRuntime = sdk.GameRuntime;
-const MESSAGE_TYPES = sdk.MESSAGE_TYPES;
-
-const runtime = new GameRuntime({
-  role: 'host',
-  debug: true
-});
-
-runtime.init();
-```
-
-### script 方式
-
-```html
-<script src="./dist/kadou-game-sdk.umd.min.js"></script>
-<script>
-  var GameRuntime = window.KadouGameSDK.GameRuntime;
-  var MESSAGE_TYPES = window.KadouGameSDK.MESSAGE_TYPES;
-
-  var runtime = new GameRuntime({
-    role: 'host',
-    debug: true
-  });
-
-  runtime.init();
-</script>
-```
-
----
-
-## Host 宿主页接入
-
-下面是宿主页最常见的接入方式。
-
-```js
-import { GameRuntime } from 'kadou-game-sdk';
-
-const iframe = document.getElementById('gameIframe');
-
-const runtime = new GameRuntime({
-  role: 'host',
-  selfWindow: window,
-  targetWindow: iframe.contentWindow,
-  targetOrigin: '*',
-  allowedOrigins: ['*'],
-  debug: true
-});
-
-runtime.init();
-
-runtime.on('game:ready', function (payload) {
-  console.log('game ready', payload);
-});
-
-runtime.on('question:submit', function (payload) {
-  console.log('学生单题提交答案', payload);
-});
-
-runtime.on('result:report', function (payload) {
-  console.log('游戏报告', payload);
-});
-
-runtime.notifySdkReady();
-
-runtime.loadGame({
-  gameId: 'game_001',
-  title: '动物单词挑战赛',
-  questionCount: 10
-});
-
-runtime.applyTheme('theme-default', {
-  startPage: {
-    title: '动物单词挑战赛',
-    desc: '本轮共 10 题，答对越多得分越高',
-    buttonText: '立即开始'
-  },
-  endPage: {
-    title: '挑战完成',
-    buttonText: '再来一次'
-  }
-});
-
-runtime.showStartPage({
-  title: '动物单词挑战赛',
-  desc: '点击开始进入游戏',
-  buttonText: '开始挑战'
-});
-```
-
----
-
-## Game 游戏页接入
-
-iframe 游戏页中一般这样接入：
-
-```js
-import { GameRuntime } from 'kadou-game-sdk';
-
-const runtime = new GameRuntime({
-  role: 'game',
-  selfWindow: window,
-  targetWindow: window.parent,
-  targetOrigin: '*',
-  allowedOrigins: ['*'],
-  root: document.body,
-  debug: true
-});
-
-runtime.init();
-
-runtime.on('sdk:ready', function () {
-  console.log('宿主页 SDK 已准备完成');
-});
-
-runtime.on('game:load', function (payload) {
-  console.log('收到游戏配置', payload);
-
-  runtime.showStartPage({
-    title: payload.title || '游戏开始',
-    desc: '准备好后点击开始',
-    buttonText: '立即开始'
-  });
-});
-
-runtime.on('theme:update', function (payload) {
-  console.log('收到主题', payload);
-});
-
-runtime.on('game:start', function () {
-  console.log('游戏开始');
-  startRealGame();
-});
-
-runtime.on('game:restart', function () {
-  console.log('重新开始');
-  restartRealGame();
-});
-
-runtime.gameReady();
-
-function startRealGame() {
-  // 你的真实游戏逻辑
-}
-
-function restartRealGame() {
-  // 你的重开逻辑
-}
-```
-
-## API 文档
-
-## GameRuntime
-
-`GameRuntime` 是 SDK 对外的核心类。
-
-### 引入
-
-```js
-import { GameRuntime } from 'kadou-game-sdk';
-```
-
-### 创建实例
-
-```js
-const runtime = new GameRuntime(options);
-```
-
-### options 参数
-
-```js
-{
-  root,
-  debug,
-  role,
-  selfWindow,
-  targetWindow,
-  targetOrigin,
-  allowedOrigins,
-  source
-}
-```
-
-### 示例
-
-```js
-const runtime = new GameRuntime({
-  root: document.body,
-  role: 'game',
-  selfWindow: window,
-  targetWindow: window.parent,
-  targetOrigin: '*',
-  allowedOrigins: ['*'],
-  debug: true
-});
-```
-
----
-
-## 实例方法
-
-### 生命周期
-
-#### `init()`
-
-启动 SDK，开始监听消息。
-
-```js
-runtime.init();
-```
-
-#### `destroy()`
-
-销毁 SDK，移除消息监听，隐藏覆盖层，清理事件。
-
-```js
-runtime.destroy();
-```
-
-### 基础设置
-
-#### `setTargetWindow(win)`
-
-设置消息发送目标窗口。
-
-```js
-runtime.setTargetWindow(iframe.contentWindow);
-```
-
-#### `setTargetOrigin(origin)`
-
-设置消息发送目标 origin。
-
-```js
-runtime.setTargetOrigin('*');
-```
-### 通用消息发送
-
-#### `send(type, payload, meta)`
-
-底层通用发送方法。
-
-```js
-runtime.send('CUSTOM_EVENT', { a: 1 });
-```
-
-### Ready / 心跳
-
-#### `notifySdkReady(extra)`
-
-通知对端：SDK 已准备完成。
-
-```js
-runtime.notifySdkReady();
-```
-
-#### `gameReady(extra)`
-
-通知对端：游戏已准备完成。
-
-```js
-runtime.gameReady();
-```
-
-#### `heartbeatPing(extra)`
-
-发送心跳检测。
-
-```js
-runtime.heartbeatPing();
-```
-
-### 游戏生命周期
-
-#### `loadGame(config)`
-
-发送游戏加载配置。
-
-```js
-runtime.loadGame({
-  gameId: 'g001',
-  title: '词汇闯关'
-});
-```
-
-#### `gameLoading(config)`
-
-发送游戏加载中进度或状态。
-
-```js
-runtime.gameLoading({
-  progress: 60
-});
-```
-
-#### `gameLoaded(config)`
-
-发送游戏加载完成。
-
-```js
-runtime.gameLoaded({
-  success: true
-});
-```
-
-#### `startGame(data)`
-
-开始游戏。
-
-```js
-runtime.startGame({
-  from: 'host'
-});
-```
-
-#### `restartGame(data)`
-
-重新开始游戏。
-
-```js
-runtime.restartGame();
-```
-
-#### `pauseGame(data)`
-
-暂停游戏。
-
-```js
-runtime.pauseGame();
-```
-
-#### `resumeGame(data)`
-
-恢复游戏。
-
-```js
-runtime.resumeGame();
-```
-
-#### `finishGame(result)`
-
-结束游戏。
-
-```js
-runtime.finishGame({
-  score: 88
-});
-```
-
-#### `destroyGame(data)`
-
-销毁游戏。
-
-```js
-runtime.destroyGame();
-```
-
-#### `showGameRank(data)`
-
-显示排行榜。
-
-```js
-runtime.showGameRank({
-  from: 'end-page'
-});
-```
-
-### 主题与配置
-
-#### `updateTheme(theme)`
-
-兼容旧接口，直接发送主题对象。
-
-```js
-runtime.updateTheme({
-  bg: 'xxx.png'
-});
-```
-
-#### `applyTheme(themeKey, themeConfig, extra)`
-
-推荐使用。发送主题 key 与主题配置。
-
-```js
-runtime.applyTheme('theme-default', {
-  startPage: {
-    title: '欢迎开始'
-  },
-  endPage: {
-    title: '挑战完成'
-  }
-});
-```
-
-#### `updateConfig(config)`
-
-更新配置。
-
-```js
-runtime.updateConfig({
-  volume: 0.8
-});
-```
-
-### 页面控制
-
-#### `showStartPage(data)`
-
-请求显示开始页。
-
-```js
-runtime.showStartPage({
-  title: '动物单词挑战赛',
-  desc: '共 10 题',
-  buttonText: '立即开始'
-});
-```
-
-#### `showEndPage(data)`
-
-请求显示结束页。
-
-```js
-runtime.showEndPage({
-  title: '挑战完成',
-  score: 100,
-  buttonText: '再来一次'
-});
-```
-
-### 题目 / 答题流程
-
-#### `submitQuestion(data)`
-
-提交题目或学生答案。
-
-```js
-runtime.submitQuestion({
-  questionId: 'q1',
-  answer: 'A'
-});
-```
-
-#### `startAnswer(data)`
-
-开始答题。
-
-```js
-runtime.startAnswer({
-  questionId: 'q1'
-});
-```
-
-#### `prevQuestion(data)`
-
-上一题。
-
-```js
-runtime.prevQuestion();
-```
-
-#### `nextQuestion(data)`
-
-下一题。
-
-```js
-runtime.nextQuestion();
-```
-
-#### `completedAnswer(data)`
-
-答题完成。
-
-```js
-runtime.completedAnswer({
-  correct: 8,
-  total: 10
-});
-```
-
-### 音量与扩展
-
-#### `changeVolume(data)`
-
-调节音量。
-
-```js
-runtime.changeVolume({
-  bgmVolume: 0.8,//背景音
-  bgmMuted: false,
-  sfxVolume: 0.6,//音效
-  sfxMuted: false
-});
-```
-
-#### `extensionEvent(extra)`
-
-发送扩展事件。
-
-```js
-runtime.extensionEvent({
-  type: 'custom-action',
-  payload: {
-    foo: 1
-  }
-});
-```
-
-### 错误与状态
-
-#### `reportError(error)`
-
-上报错误。
-
-```js
-runtime.reportError(new Error('资源加载失败'));
-```
-
-或
-
-```js
-runtime.reportError({
-  code: 'LOAD_ERROR',
-  message: '资源加载失败'
-});
-```
-
-#### `getState()`
-
-获取当前状态。
-
-```js
-const state = runtime.getState();
-```
-
-返回值：
-
-```js
-{
-  sdkReady: false,
-  gameReady: false,
-  started: false,
-  paused: false,
-  destroyed: false
-}
-```
-
-#### `isReady()`
-
-是否同时满足 SDK ready 与 Game ready。
-
-```js
-if (runtime.isReady()) {
-  console.log('可开始通信');
-}
-```
-
-### 主题加载辅助方法
-
-#### `loadThemeByUrl(url, callback)`
-
-按 URL 直接加载主题。
-
-```js
-runtime.loadThemeByUrl('/themes/default/theme.js', function (themeConfig) {
-  runtime.applyTheme('default', themeConfig);
-});
-```
-
-#### `ensureTheme(themeKey, themeRoot, callback)`
-
-确保某个主题已加载。
-
-```js
-runtime.ensureTheme('default', '/themes/', function (themeConfig) {
-  runtime.applyTheme('default', themeConfig);
-});
-```
-
-#### `buildThemeUrl(themeRoot, themeKey)`
-
-## 实例事件
-
-SDK 内部会把消息转换为事件，外部可以通过 `on` 监听。
-
-### 基础监听
-
-```js
-runtime.on('game:ready', function (payload, message, context) {
-  console.log(payload);
-});
-```
-
-### 通用消息监听
-
-#### `message`
-
-监听所有消息。
-
-```js
-runtime.on('message', function (message, context) {
-  console.log('所有消息', message, context);
-});
-```
-
-### Ready 相关
-
-- `sdk:ready`
-- `game:ready`
-
-### 游戏生命周期
-
-- `game:load`
-- `game:loaded`
-- `game:loading`
-- `game:start`
-- `game:restart`
-- `game:pause`
-- `game:resume`
-- `game:finish`
-- `game:destroy`
-- `game:rank`
-
-### 配置 / 主题
-
-- `theme:update`
-- `config:update`
-
-### 页面相关
-
-- `page:start:show`
-- `page:end:show`
-
-### 题目 / 答题
-
-- `question:submit`
-- `answer:start`
-- `question:prev`
-- `question:next`
-- `answer:completed`
-
-### 结果 / 错误 / 心跳
-
-- `result:report`
-- `error`
-- `heartbeat:ping`
-- `heartbeat:pong`
-
-### 扩展
-
-- `extension:event`
-- `volume:change`
-
----
-
-## 状态字段
-
-SDK 内部维护了以下状态：
-
-```js
-{
-  sdkReady: false,
-  gameReady: false,
-  started: false,
-  paused: false,
-  destroyed: false
-}
-```
-
-### 字段含义
-
-- `sdkReady`: 宿主 SDK 是否 ready
-- `gameReady`: 游戏页是否 ready
-- `started`: 游戏是否开始
-- `paused`: 游戏是否暂停
-- `destroyed`: 是否已经销毁
-
----
-
-## 消息流转时序
-
-### 1. 正常初始化时序
-
-```text
-Host 页面                         Game 页面
-   |                                |
-   |------ init() ----------------->|
-   |                                |
-   |------ notifySdkReady() ------->|
-   |                                |
-   |<--------- sdk:ready -----------|
-   |                                |
-   |<--------- gameReady() ---------|
-   |                                |
-   |------ loadGame(config) ------->|
-   |                                |
-   |------ applyTheme(...) -------->|
-   |                                |
-   |------ showStartPage() -------->|
-   |                                |
-   |<----- 用户点击开始页按钮 ------|
-   |                                |
-   |<--------- startGame() ---------|
-   |                                |
-   |------ 游戏正式开始 ------------>|
-```
-
-### 2. 游戏结束时序
-
-```text
-Game 页面                          Host 页面
-   |                                |
-   |------ finishGame(result) ----->|
-   |                                |
-   |------ completedAnswer() ------>|
-   |                                |
-   |------ result report ---------->|
-   |                                |
-   |<----- showEndPage(data) -------|
-   |                                |
-   |<----- 用户点击再来一次 --------|
-   |                                |
-   |------ restartGame() ---------->|
-```
-
-
-## License
-
-MIT
+# kadou-game-sdk
+
+## 安装
+
+```bash
+npm install kadou-game-sdk
+```
+
+## 导出内容
+
+```js
+import KadouGameSDK, {
+  SDK_VERSION,
+  MESSAGE_TYPES,
+  EventEmitter,
+  MessageBus,
+  GameRuntime
+} from 'kadou-game-sdk';
+```
+
+## 快速使用
+
+
+```js
+import { GameRuntime } from 'kadou-game-sdk';
+
+const runtime = new GameRuntime({
+  role: 'game',
+  targetWindow: window.parent,
+  targetOrigin: '*',
+  root: document.body,
+  debug: true
+});
+
+runtime.init();
+runtime.gameReady();
+
+runtime.on('game:start', function () {
+  console.log('游戏开始');
+});
+```
+
+## 常用能力
+
+`GameRuntime` 提供的常用能力包括生命周期控制、页面控制、答题事件上报、主题与配置下发、心跳检测和错误上报。相关方法包括 `startGame`、`pauseGame`、`resumeGame`、`finishGame`、`restartGame`、`showStartPage`、`showEndPage`、`updateConfig`、`applyTheme`、`startAnswer`、`submitQuestion`、`showAnswerPopup`、`extensionEvent` 等。
+
+## 常用事件
+
+```js
+runtime.on('sdk:ready', handler);
+runtime.on('game:ready', handler);
+runtime.on('game:start', handler);
+runtime.on('game:finish', handler);
+runtime.on('question:submit', handler);
+runtime.on('page:start:show', handler);
+runtime.on('page:end:show', handler);
+runtime.on('theme:update', handler);
+runtime.on('config:update', handler);
+runtime.on('error', handler);
+```
+
+当前 `GameRuntime` 会对游戏开始、暂停、恢复、结束、配置更新、开始页/结束页显示、答题提交、弹窗题、心跳等消息进行统一派发。
+
+## 适用场景
+
+- 宿主页面控制 iframe 游戏
+- 课堂互动游戏
+- 题卡 / 答题类 H5 游戏
+- 需要统一通信协议的小游戏容器
+
+## License
+
+MIT