From 485ed5198ed4e50935494f1a4bc8d9cc93eefc77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=BD=95=E5=86=A0=E5=B3=B0?= <33317070@qq.com>
Date: Thu, 21 May 2026 17:17:50 +0800
Subject: [PATCH] feat : vivo file system support

---
 .../Mini Game/Runtime/VivoFileSystem.meta     |  8 +++
 .../Runtime/VivoFileSystem/README.md          | 53 +++++++++++++++++++
 .../Runtime/VivoFileSystem/README.md.meta     |  7 +++
 .../Runtime/VivoFileSystem/VivoFileSystem.cs  | 34 ++++++++++++
 .../VivoFileSystem/VivoFileSystem.cs.meta     | 11 ++++
 .../Runtime/VivoFileSystem/VivoPlatform.cs    | 30 +++++++++++
 .../VivoFileSystem/VivoPlatform.cs.meta       | 11 ++++
 7 files changed, 154 insertions(+)
 create mode 100644 Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem.meta
 create mode 100644 Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md
 create mode 100644 Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md.meta
 create mode 100644 Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs
 create mode 100644 Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs.meta
 create mode 100644 Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs
 create mode 100644 Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs.meta

diff --git a/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem.meta b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem.meta
new file mode 100644
index 00000000..9ce9e0bd
--- /dev/null
+++ b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem.meta	
@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 107295423748ce54d883a768c6095b20
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
diff --git a/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md
new file mode 100644
index 00000000..e543d11a
--- /dev/null
+++ b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md	
@@ -0,0 +1,53 @@
+# vivo 小游戏文件系统
+
+该示例用于在 YooAsset 的 WebGL 运行模式下接入 vivo 小游戏。
+
+参考文档：[vivo 小游戏使用 AssetBundle 进行资源按需加载](https://h5.vivo.com.cn/vmix/vivo-unity-doc/lesson/UsingAssetBundle.html)
+
+## 环境要求
+
+先安装 vivo Unity 小游戏适配插件，并将项目切换到 WebGL 构建目标。
+
+在 WebGL Player 的 Scripting Define Symbols 中启用以下宏：
+
+- `VIVOMINIGAME`
+
+该宏是 YooAsset vivo 小游戏示例约定的编译开关，用于和其它小游戏平台适配代码保持一致。
+
+## 初始化 YooAsset
+
+在 vivo 小游戏构建中初始化 `WebPlayModeOptions` 时，使用 `VivoFileSystemCreater` 创建文件系统参数。
+
+```csharp
+#if UNITY_WEBGL && VIVOMINIGAME && !UNITY_EDITOR
+var createParameters = new WebPlayModeOptions();
+
+string defaultHostServer = GetHostServerURL();
+string fallbackHostServer = GetHostServerURL();
+string packageRoot = "/__GAME_FILE_CACHE";
+IRemoteService remoteService = new RemoteService(defaultHostServer, fallbackHostServer);
+
+createParameters.WebServerFileSystemParameters =
+    VivoFileSystemCreater.CreateFileSystemParameters(packageRoot, remoteService);
+
+var initializationOperation = package.InitializePackageAsync(createParameters);
+#endif
+```
+
+对当前文件系统来说，`packageRoot` 只需要是一个非空值。vivo 小游戏底层会对远程 AssetBundle 请求做缓存，业务侧仍然按照远程异步加载流程使用 YooAsset。
+
+## 资源包命名
+
+vivo 小游戏底层缓存依赖资源包文件名中的 hash。YooAsset 推荐只使用 `HashName` 文件命名风格。
+
+`HashName` 会生成纯 hash 文件名，例如：
+
+```text
+8d265a9dfd6cb7669cdb8b726f0afb1e.bundle
+```
+
+该命名方式和 vivo 资源缓存规则最匹配，也能避免暴露原始 Bundle 名称。vivo 小游戏构建不建议使用 `BundleName` 或 `BundleName_HashName`。
+
+## 注意事项
+
+加密 AssetBundle 仍然会走 YooAsset 常规的 Web 下载和解密流程。非加密 AssetBundle 会使用 vivo 平台适配器，并通过 `UnityWebRequestAssetBundle.GetAssetBundle` 发起请求，匹配 vivo 小游戏底层缓存流程。
diff --git a/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md.meta b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md.meta
new file mode 100644
index 00000000..c3e33e10
--- /dev/null
+++ b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/README.md.meta	
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 6c4bb9b6906c4ff09627638d90983f5b
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
diff --git a/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs
new file mode 100644
index 00000000..fdeeb6cd
--- /dev/null
+++ b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs	
@@ -0,0 +1,34 @@
+#if UNITY_WEBGL && VIVOMINIGAME
+using YooAsset;
+
+public static class VivoFileSystemCreater
+{
+    public static FileSystemParameters CreateFileSystemParameters(string packageRoot, IRemoteService remoteService)
+    {
+        string fileSystemClass = $"{nameof(VivoFileSystem)},YooAsset.MiniGame";
+        var fileSystemParams = new FileSystemParameters(fileSystemClass, packageRoot);
+        fileSystemParams.AddParameter(EFileSystemParameter.RemoteService, remoteService);
+        return fileSystemParams;
+    }
+    public static FileSystemParameters CreateFileSystemParameters(string packageRoot, IRemoteService remoteService, IBundleDecryptor decryptor)
+    {
+        string fileSystemClass = $"{nameof(VivoFileSystem)},YooAsset.MiniGame";
+        var fileSystemParams = new FileSystemParameters(fileSystemClass, packageRoot);
+        fileSystemParams.AddParameter(EFileSystemParameter.RemoteService, remoteService);
+        fileSystemParams.AddParameter(EFileSystemParameter.AssetbundleDecryptor, decryptor);
+        return fileSystemParams;
+    }
+}
+
+/// <summary>
+/// vivo 小游戏文件系统
+/// </summary>
+internal class VivoFileSystem : WebGameFileSystem
+{
+    /// <inheritdoc/>
+    protected override IWebGamePlatform CreatePlatform(string packageRoot)
+    {
+        return new VivoPlatform();
+    }
+}
+#endif
diff --git a/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs.meta b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs.meta
new file mode 100644
index 00000000..040e69f8
--- /dev/null
+++ b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoFileSystem.cs.meta	
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 0b9e45a6f7b04d94bb95fddf3fd81347
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
diff --git a/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs
new file mode 100644
index 00000000..1b1e9f69
--- /dev/null
+++ b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs	
@@ -0,0 +1,30 @@
+#if UNITY_WEBGL && VIVOMINIGAME
+using UnityEngine;
+using UnityEngine.Networking;
+using YooAsset;
+
+/// <summary>
+/// vivo 小游戏平台实现
+/// </summary>
+internal class VivoPlatform : IWebGamePlatform
+{
+    /// <inheritdoc/>
+    public UnityWebRequest CreateAssetBundleRequest(string url)
+    {
+        return UnityEngine.Networking.UnityWebRequestAssetBundle.GetAssetBundle(url);
+    }
+
+    /// <inheritdoc/>
+    public AssetBundle ExtractAssetBundle(UnityWebRequest request)
+    {
+        var downloadHandler = (DownloadHandlerAssetBundle)request.downloadHandler;
+        return downloadHandler.assetBundle;
+    }
+
+    /// <inheritdoc/>
+    public void UnloadAssetBundle(AssetBundle assetBundle, bool unloadAll)
+    {
+        assetBundle.Unload(unloadAll);
+    }
+}
+#endif
diff --git a/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs.meta b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs.meta
new file mode 100644
index 00000000..3711a4e3
--- /dev/null
+++ b/Assets/YooAsset/Samples~/Mini Game/Runtime/VivoFileSystem/VivoPlatform.cs.meta	
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: a2f8aa7e8e634d53a5025857344994cf
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: