增加资源预下载功能说明

5499e440 · ocean2o11 · 8b0e09fa · 5499e440 · 8b0e09fa · 5499e440
8 changed file
--- a/Design/PerfOptimization.md
+++ b/Design/PerfOptimization.md
@@ -26,7 +26,7 @@ Unity WebGL导出形式相对于原生APP应用，需要开发者更关注性能
 更多信息请参考：
  * [提升Unity WebGL游戏启动速度](StartupOptimization.md)
  * [首场景启动优化](FirstSceneOptimization.md)
-  * [代码分包](WasmSplit.md)
+  * [使用代码分包工具](WasmSplit.md)
 
 ### 3.2 资源按需加载
 * 尽量避免在各级Resource包含资源，该目录将被直接打包在首资源包
@@ -36,7 +36,8 @@ Unity WebGL导出形式相对于原生APP应用，需要开发者更关注性能

 更多信息请阅读:
 *  [使用Addressable进行资源按需加载](UsingAddressable.md)
-
+*  [使用 AssetBundle 进行资源按需加载](UsingAssetBundle.md)
+*  [使用预下载功能](UsingPreload.md)

 ### 3.3 资源处理建议
 * 贴图maxsize尽量不超过1024，小游戏环境适当降低画质

--- a/Design/Plugin.md
+++ b/Design/Plugin.md
-# 使用Loader进行游游戏加载
-
-## 一、什么是Unity Loader？
-Unity Loader是在微信小游戏环境加载Unity WebGL游戏的加载与适配器，使用微信小游戏插件技术开发，功能包括：
- WebAssembly代码分包加载与编译
- 资源加载与编译
- 启动进度显示
- 缓存策略
- 数据上报
-
-## 二、如何使用Unity Loader插件
-生成微信小游戏项目时，转换工具会在`game.json`中声明：
-```json
-"plugins": {
-    "UnityPlugin": {
-        "version": "major.minor.patch", // 可切换版本号
-        "provider": "wxe5a48f1ed5f544b7",
-        "contexts": [
-            {
-                "type": "isolatedContext"
-            }
-        ]
-    }
-}
-```
-这部分配置表示使用Unity Loader插件进行游戏加载，开发者无需手动修改
-
-首次使用时，会提示添加插件，按提示添加即可
-<image src="../image/addPlugin.png">
-
-## 三、配置Unity Loader功能
-### 3.1 封面视频
-由于Unity WebGL启动加载需要一定时间，因此需要使用视频或图片等内容作为过渡以留住玩家。Unity Loader默认使用视频+进度信息呈现，开发者可以自定义封面视频，可参考[启动Loader视频规范](video.md)进行配置。
-
-
-### 3.2 预加载资源
-为了充分利用网络带宽，在网络空闲时，比如下载完小游戏分包和首包资源后，可以预加载游戏需要用到的AB包。
-``` js
-let managerConfig = {
-  /* 省略其他配置 */
-
-  /** 
-   * 假设: AB包打包到 path1/StreamingAssets/WebGL这个目录下; STREAMING_CDN是以path1为根路径上传到服务器的CDN地址
-   */
-  // 需要在网络空闲时预加载的资源，支持如下形式的路径。
-  preloadDataList: [
-    // '$STREAM_CDN/StreamingAssets/WebGL/textures_8d265a9dfd6cb7669cdb8b726f0afb1e',
-    // '/WebGL/sounds_97cd953f8494c3375312e75a29c34fc2'
-  ],
-}
-```
-
-## 3.3 缓存策略
-由于缓存目录最大不可超过200M，在下载资源包、下载AB包时，若剩余空间不足以缓存，会进行缓存淘汰。目前规则比较简单，如下：
-1. 如果所需空间过大，超过最大限制：下载完成后不缓存文件，也不执行清理逻辑，直接返回下载内容。
-2. 清理部分文件可以缓存新文件：按最近使用时间从前往后排序清理，直到清理出所需空间。
-
-> 因为文件解压只能解压到用户目录，所以，若压缩文件过大，无法解压到用户目录时，会返回失败。
- 
-
-### 3.4 可交互视频
-***这个配置目前不是对所有游戏适用***
-可交互视频相比默认版本的启动页，交互性更强，用户可以通过操作（目前是点击）来切换画面。
-可交互视频实际是多段视频，通过点击来切换视频。
-视频是流式加载，但也需要平衡好视频质量和视频大小，避免抢占带宽，影响游戏主要启动流程。
-``` js
-// 是否开启可交互视频
-const NEED_INTERACTION = false
-
-// 需要使用可交互视频方案时，需要引入这两个文件
-import PageManager from './loading/pageManager'
-import VideoManager from './loading/videoManager'
-
-if (NEED_INTERACTION) {
-  const videoManager = new VideoManager({
-    // 填写一个或多个视频视频地址，可选择传入视频封面
-    videoList: [
-      // {
-      //   src: '',
-      //   poster: ''
-      // },
-      // {
-      //   src: '',
-      //   poster: ''
-      // }
-    ]
-  })
-  const pageManager = new PageManager({
-    // jumpBtnImg: 'images/jump-btn.png', // 跳过按钮图片地址，可本地，可远程
-    // continueBtnImg: 'images/PageTip.png', // 点击继续按钮图片地址，可本地，可远程
-  })
-  managerConfig = {
-    ...managerConfig,
-    // 可交互视频相关配置
-    finalPageVideoUrl: '', // 点击跳过后，循环播放的视频地址，不传默认使用LOADING_VIDEO_URL
-    videoManager,
-    pageManager,
-    probability: 0.3, // 可交互视频出现概率
-  }
-
-  // 点击跳过按钮
-  pageManager.eventEmitter.once('jumpClick', () => {
-    const gameManager = GameGlobal.manager
-    if (gameManager) {
-      gameManager.reportJump()
-      gameManager.showFinalPage()
-    }
-  })
-  // 点击继续按钮
-  pageManager.eventEmitter.on('continueClick', () => {
-    videoManager.continue()
-  })
-  // 可交互视频播放完毕
-  videoManager.once('allvideoEnd', () => {
-    const gameManager = GameGlobal.manager
-    pageManager.hideContinueBtn()
-    gameManager && gameManager.showFinalPage()
-  })
-  // 每段视频开始前，隐藏点击继续按钮
-  videoManager.on('oneVideoStart', () => {
-    pageManager.hideContinueBtn()
-  })
-  // 每段视频播放完毕，显示点击继续按钮
-  videoManager.on('oneVideoEnd', () => {
-    pageManager.showContinueBtn()
-  })
-}
-```
-### 3.5 手动可配置参看
-在`game.js`中修改插件配置
-### 基本配置
-```js
-let managerConfig = {
-  DATA_FILE_MD5: "$DATA_MD5", // 转换脚本自动填写，无需关注
-  CODE_FILE_MD5: "$CODE_MD5", // 转换脚本自动填写，无需关注
-  GAME_NAME: "$GAME_NAME", // 转换脚本自动填写，无需关注
-  DATA_FILE_SIZE: "$DATA_FILE_SIZE", // 资源文件大小，自动填写无需关注
-
-  APPID: "$APP_ID", // 转换脚本自动填写，无需关注
-  LOADING_VIDEO_URL: "$LOADING_VIDEO_URL", // 默认加载视频地址
-  DATA_CDN: "$DEPLOY_URL", // 下载资源文件的CDN
-  STREAMING_CDN: "$STREAM_CDN", // AB包存放地址，有用到AB包时需要填写
-}
-```
\ No newline at end of file
--- a/Design/StartupOptimization.md
+++ b/Design/StartupOptimization.md
@@ -41,7 +41,7 @@ WASM分包的大小会直接影响代码下载时长以及程序初始化编译
 >3. WASM编译对于低端机来说时间依然可观
 >4. WASM编译在中高端机器很快，但对于低端机来说时间依然可观

-我们建议原始代码包**不超过30MB**, 此处建议开发者**勾选"Strip Engine Code"并设置"Managed Stripping Level"为High**。同时，开发者可以使用[代码分包](WasmSplit.md)工具将代码包减少到原始尺寸的到1/3。
+我们建议原始代码包**不超过30MB**, 建议开发者**勾选"Strip Engine Code"并设置"Managed Stripping Level"为High**。同时，强烈建议开发者可以使用[代码分包](WasmSplit.md)工具将代码包减少到原始尺寸的到1/3。

 ### 2.2.3 引擎初始化与开发者首帧逻辑
 在timelog中呈现的首场景耗时即为引擎初始化与开发者首帧逻辑，关于该阶段耗时，开发者需要注意的是：
@@ -49,6 +49,8 @@ WASM分包的大小会直接影响代码下载时长以及程序初始化编译
 >2. 初始场景不宜过大，通常呈现Splah场景即可
 >3. 初始场景中需要后续主场景或配置加载时可采取分帧策略，切勿在Start/Awake阻塞。

+我们建议开发者[使用预下载功能](Design/UsingPreload.md)，该功能可以利用此阶段的网络空闲期进行资源下载。
+
 ### 2.2.4 游戏内资源按需加载
 前面我们提到开发者需要将资源从首包分离以较少首屏加载时间，同理，而对于其余的资源开发者最好使用按需加载的方式进行加载，减少玩家进行核心玩法的等待时间。
 优化可参考 [使用Addressable Assets System进行资源按需加载](UsingAddressable.md)。

--- a/Design/UsingAddressable.md
+++ b/Design/UsingAddressable.md
@@ -214,10 +214,8 @@ public async Start() {
 ### 6.1  Addressable编译与部署
 默认情况下，当编译Addressable资源时会输出到Library/com.unity.addressables/，项目发布为WebGL或转换为小游戏时Unity会自动拷贝Bundle文件到最终的生成目录下。我们只需要将对应的StreammingAssets上传到对应的CDN服务器即可。

-### 6.2 资源预加载
-<image src='../image/addressable10.png' width="700"/>
-我们可以根据资源的加载时序以及重要程度，修改game.js文件填写预加载资源列表。小游戏加载框架将利用网络空闲期进行资源预加载。
- 
+### 6.2 资源预下载
+ 为了充分利用网络带宽，在网络空闲时可预下载游戏需要用到的AB包。详细配置请参考[使用预下载功能](UsingPreload.md)。


 ### 五、参考资料

--- a/Design/UsingLoader.md
+++ b/Design/UsingLoader.md
@@ -83,22 +83,9 @@ let managerConfig = {
 ```
 - 若手动将`loadDataPackageFromSubpackage`改为false，需要将webgl目录下的资源包上传到CDN，并将CDN地址填写到game.js`DATA_CDN`字段
 - 同样的，若手动将`loadDataPackageFromSubpackage`改为true，需要将webgl目录下的资源包copy到minigame/data-package下
-### 3.3 预加载资源
-为了充分利用网络带宽，在网络空闲时，比如下载完小游戏分包和首包资源后，可以预加载游戏需要用到的AB包。
-``` js
-let managerConfig = {
-  /* 省略其他配置 */

-  /** 
-   * 假设: AB包打包到 path1/StreamingAssets/WebGL这个目录下; STREAMING_CDN是以path1为根路径上传到服务器的CDN地址
-   */
-  // 需要在网络空闲时预加载的资源，支持如下形式的路径。
-  preloadDataList: [
-    // '$STREAM_CDN/StreamingAssets/WebGL/textures_8d265a9dfd6cb7669cdb8b726f0afb1e',
-    // '/WebGL/sounds_97cd953f8494c3375312e75a29c34fc2'
-  ],
-}
-```
+### 3.3 预加载资源
+ 为了充分利用网络带宽，在网络空闲时可预下载游戏需要用到的AB包。详细配置请参考[使用预下载功能](UsingPreload.md)。

 ### 3.4 资源缓存与淘汰策略
 #### 资源缓存

--- a/Design/UsingPreload.md
+++ b/Design/UsingPreload.md
+# 使用预下载功能
+## 概述
+通过 [启动流程与时序](Design/Startup.md)我们知道，在UnityLoader加载过程中存在网络空闲的情况。特别是“引擎初始化和首场景准备”，影响该步骤包括：引擎自身模块与数据初始化，游戏首个场景加载以及Awake流程。这个过程是CPU处理密集，但网络空闲的期间，根据机型性能不同，通常平均耗时会在3~6s左右，我们可以在此阶段提前下载资源。
+
+
+## 配置预下载列表
+<image src='../image/usingpreload1.png' width="500"/>
+
+在Unity转换导出插件填写文件列表，生成时工具会自动从webgl/StreamAssets目录找资源并填充到game.js。
+运行时UnityLoader将根据列表内容在网络空闲期下载。
+
+
+
+## 注意事项
+1. 预下载所有文件总体积应控制在合理范围内，通常可以3~5MB左右的内容。
+2. 文件数量应控制在10个以内，在此阶段最多只能允许10个并发，超过将会排队。
+3. UnityLoader插件已经考虑到业务会重复请求预下载的文件，游戏逻辑依然按未使用预下载的异步记载逻辑去些，如果预下载完成插件会立即返回内容，业务无感知。
\ No newline at end of file
--- a/README.md
+++ b/README.md
@@ -26,13 +26,13 @@
  - [使用 Loader 进行游游戏加载](Design/UsingLoader.md)
  - [使用 Addressable 进行资源按需加载](Design/UsingAddressable.md)
  - [使用 AssetBundle 进行资源按需加载](Design/UsingAssetBundle.md)
+  - [使用预下载功能](Design/UsingPreload.md)
  - [首场景启动优化](Design/FirstSceneOptimization.md)
+  - [使用代码分包工具](Design/WasmSplit.md)
  - [启动留存数据上报统计](Design/ReportStartupStat.md)
-  - [代码分包](Design/WasmSplit.md)
  - [使用水印保护代码包安全](Design/wasmWaterMark.md)

 - 运行性能
-
  - [使用 Android CPU Profiler 性能调优](Design/AndroidProfile.md)
  - [使用 Unity Profiler 性能调优](Design/UnityProfiler.md)
  - [音频适配优化](Design/AudioOptimization.md)

--- a/image/usingpreload1.png
+++ b/image/usingpreload1.png