Version: v3

Global Configuration

Important Attention Reminder

Coding Style wiki

PatchSettings Description

Learn about the global configuration file; you can customize the file name and extension (found under Resources).

Create the configuration file via right-click (Right-click in Project window -> Create -> OxGFrame -> Create Settings -> Create Patch Settings in Resources).

Important Please put the configuration file under the Resources folder.

Attention Additionally, see YooAsset Global Configuration.

CryptogramSettings Description

Used for configuring encryption keys.

Create the configuration file via right-click (Right-click in Project window -> Create -> OxGFrame -> Create Settings -> Create Cryptogram Settings).

PatchLauncher Description

PatchLauncher is the runtime configuration and must be dragged into the scene as the sole runtime configuration.

PlayMode

Bundle resource hot-update mode.

Editor Simulate Mode (Development Mode)
Offline Mode (Offline Mode)
Host Mode (Online Mode)
Weak Host Mode (Weak Online Mode). Must be online for the first startup to complete initial configuration recording and resource download.
- Attention: "Play-while-downloading" is not recommended. If the connection is lost, the system will perform an integrity check on the manifest of the previous resource version.
- Additionally, if Repair is performed after suddenly losing internet, and incomplete resources are detected, a PatchVersionUpdateFailed event will be sent (because it must restart from the process of obtaining resource version; once network is restored, the remote version can be correctly obtained for updating).
WebGL Mode (WebGL Mode). Only requests resources in its own StreamingAssets.
WebGL Remote Mode (WebGL Online Mode). Can request resources from remote CDN, not limited to its own StreamingAssets.
Custom Mode (Custom Mode). Dedicated for mini-games.

CustomMode

CustomMode supports custom YooAsset package running modes (The process is complex, pay attention to the initial steps).

Used for: WeChat Mini Game, Douyin Mini Game, Alipay Mini Game, TapTap Mini Game, CustomPlayModeParameters, etc.
Note: When using CustomMode, all YooAsset package initializations need to be implemented yourself.
CustomMode Initialization Process Overview:
1. Check if there are Preset Packages requirements.
2. If so, you can customize and set AssetPatcher.SetPresetPackages(List<AppPackageInfoWithBuild> appPackages, List<DlcPackageInfoWithBuild> dlcPackages).
3. Regardless of whether there are Preset Packages requirements, you must manually call async AssetPatcher.InitializePresetPackages().
- Poll AssetPatcher.isInitialized() to judge if the flag returns true.

CustomMode Implementation Example

CustomMode - Hotfix Initialization Process

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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 Initialization Process

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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

// Initialize Preset Packages
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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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();
 var createParametersC = packageC.initializeParameters as CustomPlayModeParameters;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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 Initialization Process

WebPlayModeParameters

// 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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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;

/**
 * Omitted... suggest referring to other modes for initial parameters
 */

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] Initialize Preset Packages
    /// </summary>
    public const string INITIALIZE_PRESET_PACKAGES = "INITIALIZE_PRESET_PACKAGES";
    
    /// <summary>
    /// [Boolean] Fetch Remote App Config File from Server
    /// </summary>
    public const string FETCH_APP_CONFIG_FROM_SERVER = "FETCH_APP_CONFIG_FROM_SERVER";
   
    /// <summary>
    /// [Boolean] Version PATCH Check Rule
    /// </summary>
    public const string SEMANTIC_RULE_PATCH = "SEMANTIC_RULE_PATCH";
   
    /// <summary>
    /// [Boolean] Whether to Automatically Check and Set Request Endpoints (Host Server, Fallback Host Server)
    /// </summary>
    public const string AUTO_CONFIGURE_SERVER_ENDPOINTS = "AUTO_CONFIGURE_SERVER_ENDPOINTS";
  
    /// <summary>
    /// [Boolean] Whether to Create PresetPackages Downloader
    /// </summary>
    public const string CREATE_PRESET_PACKAGES_DOWNLOADER = "CREATE_PRESET_PACKAGES_DOWNLOADER";
   
    /// <summary>
    /// [Boolean] Whether to Enable Disk Space Check (Checks when creating PresetPackages downloader)
    /// </summary>
    public const string ENABLE_DISK_SPACE_CHECK_FOR_PRESET_PACKAGES_DOWNLOADER = "ENABLE_DISK_SPACE_CHECK_FOR_PRESET_PACKAGES_DOWNLOADER";
   
    /// <summary>
    /// [Boolean] Whether to Check Last Local Version (Used in weak network environment)
    /// </summary>
    public const string ENABLE_LAST_LOCAL_VERSIONS_CHECK_IN_WEAK_NETWORK = "ENABLE_LAST_LOCAL_VERSIONS_CHECK_IN_WEAK_NETWORK";
}

ParameterEntry

ParameterEntry list is configured in PatchLauncher, which can additionally add YooAsset FileSystem parameter configurations for different modes, but must specify the type (Reference: FileSystemParametersDefine + File System).

/// <summary>
/// Supported Types Mapping Table
/// </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

Preset package configurations for App Packages & DLC Packages, which will be updated by the AssetPatcher.Check main update phase.

Process Options, Download Options, Load Options

Related YooAsset runtime configurations and some framework configurations.

Cryptogram Options

Decryption configuration at runtime, must be set according to the instructions.

Setting format can refer to Tooltip hints.

PlayMode Macro

Building Macro (Forced to switch to this mode during release):

OXGFRAME_OFFLINE_MODE (Offline Mode)
OXGFRAME_HOST_MODE (Online Mode)
OXGFRAME_WEAK_HOST_MODE (Weak Online Mode)
OXGFRAME_WEBGL_MODE (WebGL Mode)
OXGFRAME_WEBGL_REMOTE_MODE (WebGL Online Mode)
OXGFRAME_CUSTOM_MODE (Custom Mode)

Coding Style wiki​

PatchSettings Description​

CryptogramSettings Description​

PatchLauncher Description​

PlayMode​

CustomMode​

CustomMode Implementation Example​

CustomMode - Hotfix Initialization Process​

CustomMode - Preset Packages Initialization Process​

CustomMode - Per Package Initialization Process​

PlayModeParameters​

ParameterEntry​

Preset Packages​

Process Options, Download Options, Load Options​

Cryptogram Options​

PlayMode Macro​