Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
Johnconstine
minigame-unity-webgl-transform
提交
fca306bc
M
minigame-unity-webgl-transform
项目概览
Johnconstine
/
minigame-unity-webgl-transform
与 Fork 源项目一致
从无法访问的项目Fork
通知
1
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
M
minigame-unity-webgl-transform
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
前往新版Gitcode,体验更适合开发者的 AI 搜索 >>
提交
fca306bc
编写于
6月 02, 2022
作者:
Z
zhangjunkunn
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
docs: 更新Loader文档
上级
f7355831
变更
4
隐藏空白更改
内联
并排
Showing
4 changed file
with
189 addition
and
85 deletion
+189
-85
Design/FileCache.md
Design/FileCache.md
+68
-0
Design/Transform.md
Design/Transform.md
+46
-2
Design/UsingLoader.md
Design/UsingLoader.md
+62
-79
Design/UsingPreload.md
Design/UsingPreload.md
+13
-4
未找到文件。
Design/FileCache.md
0 → 100644
浏览文件 @
fca306bc
# 资源缓存与淘汰
## 哪些资源会自动缓存?
-
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
浏览文件 @
fca306bc
...
...
@@ -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
浏览文件 @
fca306bc
...
...
@@ -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
浏览文件 @
fca306bc
# 使用预下载功能
## 概述
通过
[
启动流程与时序
](
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
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录