docs: 更新Loader文档

Design/FileCache.md

+# 资源缓存与淘汰
+
+## 哪些资源会自动缓存？
+- wasm主包/分包，即`wasm.code.unityweb`文件
+- 首包资源，即`webgl.data.unityweb`文件
+- 预加载的文件
+- 请求URL包含StreamingAssets，并且没有添加到excludeFileExtensions列表中的文件
+- 开启纹理缓存后，纹理资源
+
+
+### 转换插件相关配置
+```
+bundlePathIdentifier: 需要缓存的路径
+excludeFileExtensions: 不需要缓存的文件类型
+needCacheTextures: 是否缓存纹理
+texturesPath: 纹理存放路径
+texturesHashLength: 纹理中hash长度
+```
+
+### unity-namespace.js配置
+```js
+bundlePathIdentifier: [$BUNDLE_PATH_IDENTIFIER], // 判定为下载bundle的路径标识符，此路径下的下载，会自动缓存
+excludeFileExtensions: [$EXCLUDE_FILE_EXTENSIONS], // 命中路径标识符的情况下，并不是所有文件都有必要缓存，过滤下不需要缓存的文件拓展名
+texturesHashLength: $TEXTURE_HASH_LENGTH, // 纹理中的hash长度
+texturesPath: '$TEXTURES_PATH', // 纹理存放路径
+needCacheTextures: $NEED_CACHE_TEXTURES, // 是否需要缓存纹理
+```
+
+## 缓存规则
+> 适用于预加载的文件和URL中包含StreamingAssets的文件
+
+在写入缓存前需要经过三步
+1. 根据URL生成缓存路径
+URL剔除掉DATA_CDN部分后作为缓存路径
+例如：
+DATA_CDN=https://weixin.qq.com
+请求路径=https://weixin.qq.com/StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e
+则缓存路径=StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e
+2. 清理掉同名旧文件
+通过文件名中的hash区分同名文件的不同版本
+继续上面的例子，假如本地已经有`StreamingAssets/textures_cdb8b726f0afb1e8d265a9dfd6cb7669`
+在写入缓存前，插件认为已经本地已经有同名文件`StreamingAssets/textures`，但hash与本次写入的文件不一致，则需要删除`StreamingAssets/textures_cdb8b726f0afb1e8d265a9dfd6cb7669`
+
+转换插件相关配置
+```
+bundleHashLength: bundle中hash的长度
+```
+
+unity-namespace.js配置
+```
+bundleHashLength: $BUNDLE_HASH_LENGTH, // 自定义bundle中的hash长度
+```
+3. 检查存储空间是否足够，是否需要清理
+当已有缓存+待写入缓存超过允许的上限时，按照LRU清理出所需大小
+
+转换插件相关配置
+```
+defaultReleaseSize: 清理时，默认额外清理的大小
+```
+
+unity-namespace.js配置
+```
+releaseMemorySize: $DEFAULT_RELEASE_SIZE, // 单位Bytes, 1MB = 1024 KB = 1024*1024Bytes
+```
+
+## 注意项
+1. 文件名需要带上hash [BuildAssetBundleOptions.AppendHashToAssetBundleName](https://docs.unity3d.com/ScriptReference/BuildAssetBundleOptions.AppendHashToAssetBundleName.html)，以便清理掉该文件的旧缓存。默认32位长度，可通过导出选项中`Bundle名中Hash长度`来自定义。比如游戏自己计算了crc，可将`Bundle名中Hash长度`设置为crc长度。
+2. 配置到不自动缓存文件类型中的文件，不会自动缓存，默认值是json，比如addressable打包后生成StreamingAssets/aa/WebGL/catalog.json，这个文件不会自动缓存。
\ No newline at end of file

Design/Transform.md

@@ -27,7 +27,7 @@
 - 加载阶段视频URL：启动需要一定耗时，在启动加载时会循环播放这段视频，视频格式请参考[视频规范](video.md)
 - 启动背景/视频封面图：启动阶段背景图片；如果配置了加载阶段视频URL，则作为视频封面。
 - 游戏方向：游戏是横屏还是竖屏，可选值参考[deviceOrientation](https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html)
-- 不自动缓存文件类型：游戏资源CDN下不自动缓存的文件类型，具体参见[AssetBundle缓存]](UsingLoader.md)
+- 不自动缓存文件类型：游戏资源CDN下不自动缓存的文件类型，具体参见[AssetBundle缓存](UsingLoader.md)
 - Bundle名中Hash长度：自定义AssetBundle名中Hash长度用于缓存控制，具体参见[AssetBundle缓存](UsingLoader.md)
 - 预下载列表：网络空闲时预下载的资源，[使用预下载](UsingPreload.md)
 - SDK功能选项：[好友关系链](OpenData.md) [音频优化](AudioOptimization.md)
@@ -41,12 +41,56 @@
 至此，可以在[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)打开转化后的小游戏进行预览。
  
 ## 三、使用脚本集成到自己的构建系统
-如果你希望将导出插件集成到自己的发布流程，想脚本调用的话，可修改 Assets/WX-WASM-SDK/Editor/MiniGameConfig.asset配置，然后调用WXEditorWindow 的 DoExport方法导出小游戏   
+如果你希望将导出插件集成到自己的发布流程，想脚本调用的话，可修改 `Assets/WX-WASM-SDK/Editor/MiniGameConfig.asset`配置，然后调用WXEditorWindow 的 DoExport方法导出小游戏
  ```
  var win = new WXEditorWindow();
  win.DoExport();
  ```
 
+### `MiniGameConfig.asset`支持的配置
+#### 与转换面板配置有对应关系的配置项
+```
+// 基本设置
+Appid -- 小游戏appid
+CDN -- 游戏资源CDN
+projectName -- 小游戏项目名
+Orientation -- 游戏方向
+maxStorage -- 最大内存
+DST -- 导出路径
+// 启动Loader设置
+bgImageSrc -- 背景图/封面图
+VideoUrl -- 加载阶段视频URL
+assetLoadType -- 首包资源加载方式
+bundleExcludeExtensions -- 不自动缓存文件类型
+bundleHashLength -- bundle名中hash长度
+// 预下载
+preloadFiles -- 预下载文件列表
+// SDK功能
+UseFriendRelation -- 使用好友关系链
+UseAudioApi -- 使用微信音频API
+// 调试编译选项
+DevelopBuild -- Development Build
+AutoProfile -- Autoconnect Profiler
+ScriptOnly -- Scripts Only Build
+profilingFuncs -- Profiling Funcs
+Webgl2 -- WebGL2.0
+DeleteStreamingAssets -- DeleteStreamingAssets
+```
+#### 不常用配置
+使用说明参考[Loader配置](UsingLoader.md)
+```
+// 资源加载与缓存
+dataFileSubPrefix: 配置首包资源加载路径
+bundlePathIdentifier: URL中包含特定标识符时需要自动缓存
+defaultReleaseSize: 达到缓存上限时默认额外清理的存储大小
+needCacheTextures: 是否开启纹理缓存
+texturesPath: 纹理存储路径
+texturesHashLength: 纹理中hash长度
+// 启动界面
+loadingBarWidth: 加载进度条宽度
+HideAfterCallMain: 是否初始化完成立即隐藏封面
+```
+
 ## 四、常见问题
 1. 为什么资源或网络请求在打开"vConsole"正常，关闭时下载失败？
 网络请求必须**配置安全域名**：https://developers.weixin.qq.com/minigame/dev/guide/base-ability/network.html

Design/UsingLoader.md

@@ -30,51 +30,68 @@ Unity Loader是在微信小游戏环境加载Unity WebGL游戏的加载与适配
 <image src="../image/addPlugin.png">
 
 ## 三、配置Unity Loader功能
-以下配置都在导出的minigame/game.js中
-### 3.1 启动界面
-由于Unity WebGL启动加载需要一定时间，因此需要使用视频或图片等内容作为过渡以留住玩家。Unity Loader默认使用视频+进度信息呈现，开发者可以自定义封面视频，可参考[启动Loader视频规范](video.md)进行配置。
-界面有以下两种
-1. 使用coverview渲染进度（默认方式）
-  
-   <image src="../image/coverview_loading.png" height="500">
+### 3.1 资源下载
+声明CDN地址
+#### 转换插件相关配置
 
-   这种方式的优势在于可以覆盖因首帧逻辑过重，导致启动过程中可能出现的黑屏，等游戏画面真正出现时再隐藏启动界面
-   支持参数
-   ```js
-   loadingPageConfig: {
-      // 背景图或背景视频，两者都填时，先展示背景图，视频可播放后，播放视频
-      backgroundImage: 'images/background.jpg', // 默认的背景图，可自行替换，支持本地图片和网络图片
-      backgroundVideo: '', // 视频url，需要开发者提供，只支持网络url
-      // 以下是默认值
-      totalLaunchTime: 15000, // 默认总启动耗时，即加载动画默认播放时间，可根据游戏实际情况进行调整
-      textDuration: 1500, // 当downloadingText有多个文案时，每个文案展示时间
-      firstStartText: '首次加载请耐心等待', // 首次启动时提示文案
-      downloadingText: ['正在加载资源'], // 加载阶段循环展示的文案
-      compilingText: '编译中', // 编译阶段文案
-      initText: '初始化中', // 初始化阶段文案
-      completeText: '开始游戏', // 初始化完成
-    }
-   ```
-   > backgroundImage需要注意图片宽高不可超过2048，否则无法显示
-   > 使用coverview需要基础库版本>=2.16.1，插件已做兼容，若不支持，降级为使用离屏canvas渲染进度的方式
-2. 使用离屏canvas渲染进度
+```
+CDN: cdn地址
+dataFileSubPrefix: 首包资源相对cdn地址的存放目录，默认首包资源放在cdn一级目录
+```
+#### game.js配置
+```js
+DATA_CDN: "$DEPLOY_URL",
+```
+#### unity-namespace.js配置
+```
+dataFileSubPrefix: '$DATA_FILE_SUB_PREFIX', // DATA_CDN + dataFileSubPrefix + datafilename
+```
+### 3.2 启动界面
+由于Unity WebGL启动加载需要一定时间，因此需要使用视频或图片等内容作为过渡以留住玩家。Unity Loader默认使用视频+进度信息呈现，开发者可以自定义封面/视频，可参考[启动Loader视频规范](video.md)进行配置。
+  
+<image src="../image/coverview_loading.png" height="500">
 
-   <image src="../image/default_loading.jpg" height="500" />
+#### 转换插件相关配置
+```
+bgImageSrc: 启动封面图；-- $BACKGROUND_IMAGE
+VideoUrl: 启动视频；-- $LOADING_VIDEO_URL
+HideAfterCallMain: 是否callmain完成后立即隐藏封面；-- $HIDE_AFTER_CALLMAIN
+loadingBarWidth: 加载进度条宽度；-- $LOADING_BAR_WIDTH
+```
 
-    支持参数
-    ```js
-    let managerConfig = {
-      // ...省略其他配置
-      LOADING_VIDEO_URL: "", // 视频url
-    }
-    ```
-当基础库>=2.16.1时，默认使用coverview，否则使用离屏canvas
-### 3.2 首包资源加载方式
+#### game.js配置
+```js
+loadingPageConfig: {
+  // 背景图或背景视频，两者都填时，先展示背景图，视频可播放后，播放视频
+  backgroundImage: '$BACKGROUND_IMAGE', // 默认的背景图，可自行替换，支持本地图片和网络图片
+  backgroundVideo: '$LOADING_VIDEO_URL', // 视频url，需要开发者提供，只支持网络url
+  // 以下是默认值
+  barWidth: $LOADING_BAR_WIDTH, // 加载进度条宽度，默认240，加载文案过长时可设置
+  totalLaunchTime: 15000, // 默认总启动耗时，即加载动画默认播放时间，可根据游戏实际情况进行调整
+  textDuration: 1500, // 当downloadingText有多个文案时，每个文案展示时间
+  firstStartText: '首次加载请耐心等待', // 首次启动时提示文案
+  downloadingText: ['正在加载资源'], // 加载阶段循环展示的文案
+  compilingText: '编译中', // 编译阶段文案
+  initText: '初始化中', // 初始化阶段文案
+  completeText: '开始游戏', // 初始化完成
+},
+hideAfterCallmain: $HIDE_AFTER_CALLMAIN, // 是否callmain完成立即隐藏封面
+```
+> backgroundImage需要注意图片宽高不可超过2048，否则无法显示
+> 使用coverview需要基础库版本>=2.16.1，插件已做兼容，若不支持，降级为使用离屏canvas渲染进度的方式
+> hideAfterCallmain: 游戏业务Awake逻辑耗时较高时可能导致出现短暂黑屏，改为false可盖住黑屏，等游戏第一帧渲染时隐藏
+### 3.3 首包资源加载方式
 **加载方式在转换工具导出时就确定好了，开发者一般不需要修改**
-当游戏资源量比较少时，可选择将首包资源作为小游戏分包加载，了解[小游戏分包](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/sub-packages.html)
-wasm代码已是通过代码分包加载，当wasm代码+首包资源>20M时，资源包不可再使用小游戏分包加载。
+当**游戏资源量比较少**时，可选择将首包资源作为小游戏分包加载，了解[小游戏分包](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/sub-packages.html)
+wasm代码已是通过代码分包加载，当**wasm代码+首包资源>20M时，资源包不可再使用小游戏分包加载**。
 当首包资源通过小游戏代码分包下载时，会将首包资源存放在minigame/data-package这个分包下
-相关配置
+
+#### 转换插件相关配置
+```
+assetLoadType: -- $LOAD_DATA_FROM_SUBPACKAGE
+```
+
+#### game.js配置
 ```js
 let managerConfig = {
   /* 省略其他配置 */
@@ -84,43 +101,9 @@ let managerConfig = {
 - 若手动将`loadDataPackageFromSubpackage`改为false，需要将webgl目录下的资源包上传到CDN，并将CDN地址填写到game.js`DATA_CDN`字段
 - 同样的，若手动将`loadDataPackageFromSubpackage`改为true，需要将webgl目录下的资源包copy到minigame/data-package下
 
-### 3.3 预加载资源
- 为了充分利用网络带宽，在网络空闲时可预下载游戏需要用到的AB包。详细配置请参考[使用预下载功能](UsingPreload.md)。
-
-### 3.4 资源缓存与淘汰策略
-#### 资源缓存
-首包资源和wasm代码会自动缓存。
-
-#### assetbundle缓存
-如果请求URL包含StreamingAssets，则插件判定为是在下载assetbundle文件，会自动进行缓存提升二次启动速度。
-所以需要自动缓存的文件，可放到StreamingAssets目录下。
+### 3.4 预加载资源
+为了充分利用网络带宽，在网络空闲时可预下载游戏需要用到的AB包。详细配置请参考[使用预下载功能](UsingPreload.md)。
 
-但请注意以下几点：
-1. 文件名需要带上hash [BuildAssetBundleOptions.AppendHashToAssetBundleName](https://docs.unity3d.com/ScriptReference/BuildAssetBundleOptions.AppendHashToAssetBundleName.html)，以便清理掉该文件的旧缓存。默认32位长度，如果游戏可通过导出选项中`Bundle名中Hash长度`来自定义。比如游戏自己计算了crc，可将`Bundle名中Hash长度`设置为crc长度。
-2. 配置到不自动缓存文件类型中的文件，不会自动缓存，默认值是json，比如addressable打包后生成StreamingAssets/aa/WebGL/catalog.json，这个文件不会自动缓存。
-
-#### 资源淘汰
-由于缓存目录最大不可超过200M，在下载资源包、下载AB包时，若剩余空间不足以缓存，会进行缓存淘汰。目前规则比较简单，如下：
-1. 如果所需空间过大，超过最大限制：下载完成后不缓存文件，也不执行清理逻辑，直接返回下载内容。
-2. 清理部分文件可以缓存新文件：按最近使用时间从前往后排序清理，直到清理出所需空间。
- 
-
-### 3.5 其他可配置参看
-在`game.js`中修改插件配置
-### 基本配置
-```js
-let managerConfig = {
-  DATA_FILE_MD5: "$DATA_MD5", // 转换脚本自动填写，无需关注
-  CODE_FILE_MD5: "$CODE_MD5", // 转换脚本自动填写，无需关注
-  GAME_NAME: "$GAME_NAME", // 转换脚本自动填写，无需关注
-  APPID: "$APP_ID", // 转换脚本自动填写，无需关注
-  DATA_FILE_SIZE: "$DATA_FILE_SIZE", // 资源文件大小，自动填写无需关注
-
-  LOADING_VIDEO_URL: "$LOADING_VIDEO_URL", // 默认加载视频地址
-  DATA_CDN: "$DEPLOY_URL", // 下载资源文件的CDN
-  AUDIO_PREFIX: "$AUDIO_PREFIX", // 音频资源cdn
-  STREAMING_CDN: "$STREAM_CDN", // AB包存放地址，有用到AB包时需要填写
-  
-  loadDataPackageFromSubpackage: $LOAD_DATA_FROM_SUBPACKAGE, // 资源包是否作为小游戏分包加载
-};
-```
\ No newline at end of file
+### 3.5 资源缓存与淘汰策略
+loader会自动按一定规则做文件缓存，加快二次启动速度
+详情参考[资源缓存](FileCache.md)

Design/UsingPreload.md

 # 使用预下载功能
 ## 概述
-通过 [启动流程与时序](Startup.md)我们知道，在UnityLoader加载过程中存在网络空闲的情况。特别是“引擎初始化和首场景准备”，影响该步骤包括：引擎自身模块与数据初始化，游戏首个场景加载以及Awake流程。这个过程是CPU处理密集，但网络空闲的期间，根据机型性能不同，通常平均耗时会在3~6s左右，我们可以在此阶段提前下载资源。
-
+通过 [启动流程与时序](Startup.md)我们知道，在UnityLoader加载过程中存在**网络空闲**的情况。特别是“引擎初始化和首场景准备”，影响该步骤包括：引擎自身模块与数据初始化，游戏首个场景加载以及Awake流程。这个过程是CPU处理密集，但网络空闲的期间，根据机型性能不同，通常**平均耗时会在3~6s**左右，我们可以在此阶段提前下载资源。
 
 ## 导出预下载列表
 <image src='../image/usingpreload1.png' width="500"/>
 
-在Unity转换导出插件填写文件列表，生成时工具会自动从webgl/StreamAssets目录找资源并填充到game.js。
+#### MiniGameConfig.asset相关配置
+```
+preloadFiles: -- $PRELOAD_LIST
+```
+
+在Unity转换导出插件填写文件列表，生成时工具会自动从**webgl/StreamAssets目录**找资源并填充到game.js。
 运行时UnityLoader将根据列表内容在网络空闲期下载。
 
 ## 手动配置
@@ -22,11 +26,16 @@ let managerConfig = {
   preloadDataList: [
     // '$STREAM_CDN/StreamingAssets/WebGL/textures_8d265a9dfd6cb7669cdb8b726f0afb1e',
     // '/WebGL/sounds_97cd953f8494c3375312e75a29c34fc2'
+    "$PRELOAD_LIST" // 导出时自动替换
   ],
 }
 ```
 
+## 路径规范
+- 若填写完成路径，如`$STREAM_CDN/StreamingAssets/WebGL/textures_8d265a9dfd6cb7669cdb8b726f0afb1e`；实际发起预载请求的URL采用填写的地址
+- 若填写相对路径，如`/WebGL/sounds_97cd953f8494c3375312e75a29c34fc2`；实际发起请求的URL为`DATA_CDN/StreamingAssets/WebGL/sounds_97cd953f8494c3375312e75a29c34fc2`
+
 ## 注意事项
 1. 预下载所有文件总体积应控制在合理范围内，通常可以3~5MB左右的内容。
 2. 文件数量应控制在10个以内，在此阶段最多只能允许10个并发，超过将会排队。
-3. UnityLoader插件已经考虑到业务会重复请求预下载的文件，游戏逻辑依然按未使用预下载的异步加载逻辑。如果预下载完成UnityLoader会立即构造网络数据返回，业务无感知。
+3. UnityLoader插件已经考虑到业务会重复请求预下载的文件，游戏逻辑依然按未使用预下载的异步加载逻辑，无需做其他处理。如果预下载完成UnityLoader会立即构造网络数据返回，业务无感知。
\ No newline at end of file