版本：v3

全局配置

重要注意提醒

Coding Style wiki

PatchSettings 配置说明

了解全局配置文件，可以自行定制化文件名称与扩展名称 (在 Resources 目录下)。

通过右键创建配置文件 (Project 窗体内右键 -> Create -> OxGFrame -> Create Settings -> Create Patch Settings in Resources)。

重要请将配置文件放在 Resources 文件夹底下。

注意另外详见 YooAsset 全局配置。

CryptogramSettings 配置说明

用于加密密钥的配置。

通过右键创建配置文件 (Project 窗体内右键 -> Create -> OxGFrame -> Create Settings -> Create Cryptogram Settings)。

PatchLauncher 配置说明

PatchLauncher 为运行配置，必须拖拽于场景中作为唯一运行配置。

PlayMode

Bundle 资源热更模式。

Editor Simulate Mode (开发模式)
Offline Mode (离线模式)
Host Mode (联机模式)
Weak Host Mode (弱联机模式)，首次启动必须联机，以完成初始配置记录与资源下载。
- 注意：不建议边玩边下载，因为当失去联网时，会验证上一次资源版本的清单内容完整性。
- 另外，如果突然失去联网又进行 Repair 时，当验证到资源不完整，则会发送 PatchVersionUpdateFailed 事件 (因为必须重新从获取资源版本的流程开始运行, 只要网络恢复, 则可以正确获取到远端版本进行更新)。
WebGL Mode (WebGL 模式)，仅请求自身 StreamingAssets 中的资源。
WebGL Remote Mode (WebGL 联机模式)，可以请求远端 CDN 的资源，不仅限于自身 StreamingAssets。
Custom Mode (自定义模式)，小游戏专用。

CustomMode

CustomMode，支持自定义 YooAsset 包裹运行模式 (流程繁琐，须注意初始步骤)。

用于：微信小游戏、抖音小游戏、支付宝小游戏、TapTap 小游戏、CustomPlayModeParameters (自定义运行模式)、等等...。
注意：当使用 CustomMode，所有 YooAsset 包裹初始皆需要自行实现。
CustomMode 初始化流程概述：
1. 是否有 Preset Packages 需求。
2. 有的话，可自定义与设置 AssetPatcher.SetPresetPackages(List<AppPackageInfoWithBuild> appPackages, List<DlcPackageInfoWithBuild> dlcPackages)。
3. 不管有没有 Preset Packages 需求，都必须手动调用 async AssetPatcher.InitializePresetPackages()。
- 轮询 AssetPatcher.isInitialized() 判断标记是否返回 true。

CustomMode 实现示例

CustomMode - Hotfix 初始化流程

var hotfixPackageName = "HotfixPackage";
var hotfixPackage = new AppPackageInfoWithBuild();
hotfixPackage.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
hotfixPackage.packageName = hotfixPackageName;
hotfixPackage.hostServer = await BundleConfig.GetHostServerUrl(hotfixPackageName);
hotfixPackage.fallbackHostServer = await BundleConfig.GetFallbackHostServerUrl(hotfixPackageName);
var remoteServices = new HostServers(hotfixPackage.hostServer, hotfixPackage.fallbackHostServer);
var bundleDecryptionServices = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServices = AssetPatcher.GetManifestDecryptionServices();
hotfixPackage.initializeParameters = new WebPlayModeParameters();
var createParameters = hotfixPackage.initializeParameters as WebPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

Hotfixers.CheckHotfix
(
    // Download and load hotfix files from HotfixPackage
    hotfixPackage,
    // Metadata for AOT assemblies
    new string[]
    {
        "mscorlib.dll"
    },
    // Hotfix assemblies
    new string[]
    {
        "HotfixerDemo.Hotfix.Runtime.dll"
    }
);

CustomMode - Preset Packages 初始化流程

WebPlayModeParameters

var packageNameA = "MyCustomPackageA";
var packageA = new AppPackageInfoWithBuild();
packageA.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageA.packageName = packageNameA;
packageA.hostServer = await BundleConfig.GetHostServerUrl(packageNameA);
packageA.fallbackHostServer = await BundleConfig.GetFallbackHostServerUrl(packageNameA);
var remoteServicesA = new HostServers(packageA.hostServer, packageA.fallbackHostServer);
var bundleDecryptionServicesA = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesA = AssetPatcher.GetManifestDecryptionServices();
packageA.initializeParameters = new WebPlayModeParameters();
var createParametersA = packageA.initializeParameters as WebPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

var packageNameB = "MyCustomPackageB";
var packageB = new AppPackageInfoWithBuild();
packageB.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageB.packageName = packageNameB;
packageB.hostServer = await BundleConfig.GetHostServerUrl(packageNameB);
packageB.fallbackHostServer = await BundleConfig.GetFallbackHostServerUrl(packageNameB);
var remoteServicesB = new HostServers(packageB.hostServer, packageB.fallbackHostServer);
var bundleDecryptionServicesB = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesB = AssetPatcher.GetManifestDecryptionServices();
packageB.initializeParameters = new WebPlayModeParameters();
var createParametersB = packageB.initializeParameters as WebPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

var packageNameC = "MyCustomPackageC";
var packageC = new DlcPackageInfoWithBuild();
packageC.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageC.packageName = packageNameC;
packageC.withoutPlatform = false;
packageC.dlcVersion = "latest";
packageC.hostServer = await BundleConfig.GetDlcHostServerUrl(packageNameC, packageC.dlcVersion, packageC.withoutPlatform);
packageC.fallbackHostServer = await BundleConfig.GetDlcFallbackHostServerUrl(packageNameC, packageC.dlcVersion, packageC.withoutPlatform);
var remoteServicesC = new HostServers(packageC.hostServer, packageC.fallbackHostServer);
var bundleDecryptionServicesC = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesC = AssetPatcher.GetManifestDecryptionServices();
packageC.initializeParameters = new WebPlayModeParameters();
var createParametersC = packageC.initializeParameters as WebPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

// 设置预设包裹
AssetPatcher.SetPresetPackages
(
    new List<AppPackageInfoWithBuild>()
    {
        packageA,
        packageB,
    },
    new List<DlcPackageInfoWithBuild>()
    {
        packageC
    }
);

// 初始预设包裹
await AssetPatcher.InitializePresetPackages();

CustomPlayModeParameters

var packageNameA = "MyCustomPackageA";
var packageA = new AppPackageInfoWithBuild();
packageA.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageA.packageName = packageNameA;
packageA.hostServer = await BundleConfig.GetHostServerUrl(packageNameA);
packageA.fallbackHostServer = await BundleConfig.GetFallbackHostServerUrl(packageNameA);
var remoteServicesA = new HostServers(packageA.hostServer, packageA.fallbackHostServer);
var bundleDecryptionServicesA = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesA = AssetPatcher.GetManifestDecryptionServices();
packageA.initializeParameters = new CustomPlayModeParameters();
var createParametersA = packageA.initializeParameters as CustomPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

createParametersA.FileSystemParameterList.Add(new FileSystemParameters("A", ""));
createParametersA.FileSystemParameterList.Add(new FileSystemParameters("B", ""));
createParametersA.FileSystemParameterList.Add(new FileSystemParameters("C", ""));

var packageNameB = "MyCustomPackageB";
var packageB = new AppPackageInfoWithBuild();
packageB.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageB.packageName = packageNameB;
packageB.hostServer = await BundleConfig.GetHostServerUrl(packageNameB);
packageB.fallbackHostServer = await BundleConfig.GetFallbackHostServerUrl(packageNameB);
var remoteServicesB = new HostServers(packageB.hostServer, packageB.fallbackHostServer);
var bundleDecryptionServicesB = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesB = AssetPatcher.GetManifestDecryptionServices();
packageB.initializeParameters = new CustomPlayModeParameters();
var createParametersB = packageB.initializeParameters as CustomPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

createParametersB.FileSystemParameterList.Add(new FileSystemParameters("A", ""));
createParametersB.FileSystemParameterList.Add(new FileSystemParameters("B", ""));
createParametersB.FileSystemParameterList.Add(new FileSystemParameters("C", ""));

 var packageNameC = "MyCustomPackageC";
 var packageC = new DlcPackageInfoWithBuild();
 packageC.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
 packageC.packageName = packageNameC;
 packageC.withoutPlatform = false;
 packageC.dlcVersion = "latest";
 packageC.hostServer = await BundleConfig.GetDlcHostServerUrl(packageNameC, packageC.dlcVersion, packageC.withoutPlatform);
 packageC.fallbackHostServer = await BundleConfig.GetDlcFallbackHostServerUrl(packageNameC, packageC.dlcVersion, packageC.withoutPlatform);
 var remoteServicesC = new HostServers(packageC.hostServer, packageC.fallbackHostServer);
 var bundleDecryptionServicesC = AssetPatcher.GetBundleDecryptionServices();
 var manifestDecryptionServicesC = AssetPatcher.GetManifestDecryptionServices();
 packageC.initializeParameters = new CustomPlayModeParameters();
 packageC.initializeParameters = new CustomPlayModeParameters();
 var createParametersC = packageC.initializeParameters as CustomPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

createParametersC.FileSystemParameterList.Add(new FileSystemParameters("A", ""));
createParametersC.FileSystemParameterList.Add(new FileSystemParameters("B", ""));
createParametersC.FileSystemParameterList.Add(new FileSystemParameters("C", ""));

AssetPatcher.SetPresetPackages
(
    new List<AppPackageInfoWithBuild>()
    {
        packageA,
        packageB,
    },
    new List<DlcPackageInfoWithBuild>()
    {
        packageC
    }
);

await AssetPatcher.InitializePresetPackages();

CustomMode - Per Package 初始化流程

// Per-Package to init (APP)
var packageNameD = "MyCustomPackageD";
var packageD = new AppPackageInfoWithBuild();
packageD.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageD.packageName = packageNameD;
packageD.hostServer = await BundleConfig.GetHostServerUrl(packageNameD);
packageD.fallbackHostServer = await BundleConfig.GetFallbackHostServerUrl(packageNameD);
var remoteServicesD = new HostServers(packageD.hostServer, packageD.fallbackHostServer);
var bundleDecryptionServicesD = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesD = AssetPatcher.GetManifestDecryptionServices();
packageD.initializeParameters = new WebPlayModeParameters();
var createParametersD = packageD.initializeParameters as WebPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

await AssetPatcher.InitPackage(packageD, true);

// Per-Package to init (DLC)
var packageNameE = "MyCustomPackageE";
var packageE = new DlcPackageInfoWithBuild();
packageE.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageE.packageName = packageNameE;
packageE.withoutPlatform = false;
packageE.dlcVersion = "latest";
packageE.hostServer = await BundleConfig.GetDlcHostServerUrl(packageNameE, packageE.dlcVersion, packageE.withoutPlatform);
packageE.fallbackHostServer = await BundleConfig.GetDlcFallbackHostServerUrl(packageNameE, packageE.dlcVersion, packageE.withoutPlatform);
var remoteServicesE = new HostServers(packageE.hostServer, packageE.fallbackHostServer);
var bundleDecryptionServicesE = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesE = AssetPatcher.GetManifestDecryptionServices();
packageE.initializeParameters = new WebPlayModeParameters();
var createParametersE = packageE.initializeParameters as WebPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

await AssetPatcher.InitPackage(packageE, true);

CustomPlayModeParameters

// Per-Package to init (APP)
var packageNameD = "MyCustomPackageD";
var packageD = new AppPackageInfoWithBuild();
packageD.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageD.packageName = packageNameD;
packageD.hostServer = await BundleConfig.GetHostServerUrl(packageNameD);
packageD.fallbackHostServer = await BundleConfig.GetFallbackHostServerUrl(packageNameD);
var remoteServicesD = new HostServers(packageD.hostServer, packageD.fallbackHostServer);
var bundleDecryptionServicesD = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesD = AssetPatcher.GetManifestDecryptionServices();
packageD.initializeParameters = new CustomPlayModeParameters();
var createParametersD = packageD.initializeParameters as CustomPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

createParametersD.FileSystemParameterList.Add(new FileSystemParameters("A", ""));
createParametersD.FileSystemParameterList.Add(new FileSystemParameters("B", ""));
createParametersD.FileSystemParameterList.Add(new FileSystemParameters("C", ""));
await AssetPatcher.InitPackage(packageD, true);

// Per-Package to init (DLC)
var packageNameE = "MyCustomPackageE";
var packageE = new DlcPackageInfoWithBuild();
packageE.buildMode = BundleConfig.BuildMode.ScriptableBuildPipeline;
packageE.packageName = packageNameE;
packageE.withoutPlatform = false;
packageE.dlcVersion = "latest";
packageE.hostServer = await BundleConfig.GetDlcHostServerUrl(packageNameE, packageE.dlcVersion, packageE.withoutPlatform);
packageE.fallbackHostServer = await BundleConfig.GetDlcFallbackHostServerUrl(packageNameE, packageE.dlcVersion, packageE.withoutPlatform);
var remoteServicesE = new HostServers(packageE.hostServer, packageE.fallbackHostServer);
var bundleDecryptionServicesE = AssetPatcher.GetBundleDecryptionServices();
var manifestDecryptionServicesE = AssetPatcher.GetManifestDecryptionServices();
packageE.initializeParameters = new CustomPlayModeParameters();
var createParametersE = packageE.initializeParameters as CustomPlayModeParameters;

/**
 * 省略...建议参考其他模式初始参数
 */

createParametersE.FileSystemParameterList.Add(new FileSystemParameters("A", ""));
createParametersE.FileSystemParameterList.Add(new FileSystemParameters("B", ""));
createParametersE.FileSystemParameterList.Add(new FileSystemParameters("C", ""));
await AssetPatcher.InitPackage(packageE, true);

PlayModeParameters

public static class PlayModeParametersDefine
{
    /// <summary>
    /// [Boolean] 初始预设包裹
    /// </summary>
    public const string INITIALIZE_PRESET_PACKAGES = "INITIALIZE_PRESET_PACKAGES";
   
    /// <summary>
    /// [Boolean] 获取远端 App 版号文件
    /// </summary>
    public const string FETCH_APP_CONFIG_FROM_SERVER = "FETCH_APP_CONFIG_FROM_SERVER";
   
    /// <summary>
    /// [Boolean] 版号 PATCH 检查规则
    /// </summary>
    public const string SEMANTIC_RULE_PATCH = "SEMANTIC_RULE_PATCH";
   
    /// <summary>
    /// [Boolean] 是否自动检查与设置请求端点 (Host Server, Fallback Host Server)
    /// </summary>
    public const string AUTO_CONFIGURE_SERVER_ENDPOINTS = "AUTO_CONFIGURE_SERVER_ENDPOINTS";
    
    /// <summary>
    /// [Boolean] 是否创建 PresetPackages 下载器
    /// </summary>
    public const string CREATE_PRESET_PACKAGES_DOWNLOADER = "CREATE_PRESET_PACKAGES_DOWNLOADER";
    
    /// <summary>
    /// [Boolean] 是否检查硬盘空间 (当创建 PresetPackages 下载器时, 会进行检查)
    /// </summary>
    public const string ENABLE_DISK_SPACE_CHECK_FOR_PRESET_PACKAGES_DOWNLOADER = "ENABLE_DISK_SPACE_CHECK_FOR_PRESET_PACKAGES_DOWNLOADER";
   
    /// <summary>
    /// [Boolean] 是否检查本地最后版本 (用于弱联网环境)
    /// </summary>
    public const string ENABLE_LAST_LOCAL_VERSIONS_CHECK_IN_WEAK_NETWORK = "ENABLE_LAST_LOCAL_VERSIONS_CHECK_IN_WEAK_NETWORK";
}

ParameterEntry

ParameterEntry 列表配置于 PatchLauncher，可以针对不同模式额外新增 YooAsset FileSystem 的参数配置，但必须表明类型 (参考：FileSystemParametersDefine + 文件系统)。

/// <summary>
/// 支持的类型对应表
/// </summary>
private static readonly Dictionary<string, Type> _supportedTypes = new Dictionary<string, Type>(StringComparer.OrdinalIgnoreCase)
{
    // Boolean
    { "bool", typeof(bool) },
    { "boolean", typeof(bool) },
    
    // Integer types
    { "int", typeof(int) },
    { "int32", typeof(int) },
    { "uint", typeof(uint) },
    { "uint32", typeof(uint) },
    { "byte", typeof(byte) },
    { "sbyte", typeof(sbyte) },
    { "short", typeof(short) },
    { "int16", typeof(short) },
    { "ushort", typeof(ushort) },
    { "uint16", typeof(ushort) },
    { "long", typeof(long) },
    { "int64", typeof(long) },
    { "ulong", typeof(ulong) },
    { "uint64", typeof(ulong) },
    
    // Floating point types
    { "float", typeof(float) },
    { "single", typeof(float) },
    { "double", typeof(double) },
    { "decimal", typeof(decimal) },
    
    // Other common types
    { "string", typeof(string) },
    { "char", typeof(char) }
};

Preset Packages

预设包裹配置 App Packages & DLC Packages，将由 AssetPatcher.Check 主更新阶段进行更新。

Process Options, Download Options, Load Options

相关 YooAsset 的运行配置与部分框架配置。

Cryptogram Options

运行时的解密配置，必须依照说明进行设定。

设定格式可以参考 Tooltip 提示说明。

PlayMode Macro

打包专用 Macro (发布时，强制切换该模式)：

OXGFRAME_OFFLINE_MODE (离线模式)
OXGFRAME_HOST_MODE (联机模式)
OXGFRAME_WEAK_HOST_MODE (弱联机模式)
OXGFRAME_WEBGL_MODE (WebGL 模式)
OXGFRAME_WEBGL_REMOTE_MODE (WebGL 联机模式)
OXGFRAME_CUSTOM_MODE (自定义模式)

Coding Style wiki​

PatchSettings 配置说明​

CryptogramSettings 配置说明​

PatchLauncher 配置说明​

PlayMode​

CustomMode​

CustomMode 实现示例​

CustomMode - Hotfix 初始化流程​

CustomMode - Preset Packages 初始化流程​

CustomMode - Per Package 初始化流程​

PlayModeParameters​

ParameterEntry​

Preset Packages​

Process Options, Download Options, Load Options​

Cryptogram Options​

PlayMode Macro​