From fca306bcb8ef0c8d3557f21c12d06c045beec7ab Mon Sep 17 00:00:00 2001 From: zhangjunkunn Date: Thu, 2 Jun 2022 19:53:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0Loader=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Design/FileCache.md | 68 ++++++++++++++++++++ Design/Transform.md | 48 +++++++++++++- Design/UsingLoader.md | 141 ++++++++++++++++++----------------------- Design/UsingPreload.md | 17 +++-- 4 files changed, 189 insertions(+), 85 deletions(-) create mode 100644 Design/FileCache.md diff --git a/Design/FileCache.md b/Design/FileCache.md new file mode 100644 index 0000000..ff758e7 --- /dev/null +++ b/Design/FileCache.md @@ -0,0 +1,68 @@ +# 资源缓存与淘汰 + +## 哪些资源会自动缓存？ +- 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 diff --git a/Design/Transform.md b/Design/Transform.md index fcccc7b..1afedfb 100644 --- a/Design/Transform.md +++ b/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 diff --git a/Design/UsingLoader.md b/Design/UsingLoader.md index d5403c2..d12d061 100644 --- a/Design/UsingLoader.md +++ b/Design/UsingLoader.md @@ -30,51 +30,68 @@ Unity Loader是在微信小游戏环境加载Unity WebGL游戏的加载与适配 ## 三、配置Unity Loader功能 -以下配置都在导出的minigame/game.js中 -### 3.1 启动界面 -由于Unity WebGL启动加载需要一定时间，因此需要使用视频或图片等内容作为过渡以留住玩家。Unity Loader默认使用视频+进度信息呈现，开发者可以自定义封面视频，可参考[启动Loader视频规范](video.md)进行配置。 -界面有以下两种 -1. 使用coverview渲染进度（默认方式） - - +### 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)进行配置。 + + - +#### 转换插件相关配置 +``` +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) diff --git a/Design/UsingPreload.md b/Design/UsingPreload.md index 0674c4a..ce3c285 100644 --- a/Design/UsingPreload.md +++ b/Design/UsingPreload.md @@ -1,12 +1,16 @@ # 使用预下载功能 ## 概述 -通过 [启动流程与时序](Startup.md)我们知道，在UnityLoader加载过程中存在网络空闲的情况。特别是“引擎初始化和首场景准备”，影响该步骤包括：引擎自身模块与数据初始化，游戏首个场景加载以及Awake流程。这个过程是CPU处理密集，但网络空闲的期间，根据机型性能不同，通常平均耗时会在3~6s左右，我们可以在此阶段提前下载资源。 - +通过 [启动流程与时序](Startup.md)我们知道，在UnityLoader加载过程中存在**网络空闲**的情况。特别是“引擎初始化和首场景准备”，影响该步骤包括：引擎自身模块与数据初始化，游戏首个场景加载以及Awake流程。这个过程是CPU处理密集，但网络空闲的期间，根据机型性能不同，通常**平均耗时会在3~6s**左右，我们可以在此阶段提前下载资源。 ## 导出预下载列表 -在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 -- GitLab