Maintain Galaxy Store Compatibility for Unity Games with Play Asset Delivery
Mobassir Ahsan
Engineer, Samsung Developer Program
Play Asset Delivery (PAD) enhances the gaming experience by offering the advantages of application bundles, which are packages that group all necessary resources for efficient delivery, making downloads faster and installations smoother for players. Android App Bundles (AAB) are a type of PAD, the modern way of building and publishing Android applications and games in Google Play Store. The Samsung Galaxy Store recently introduced the option to upload AAB files to Galaxy Store Seller Portal. However, AABs have some Google Play Store proprietary features that might make a game non-functional when it is uploaded to Galaxy Store. This article explores ways in which you can utilize PAD while ensuring your game remains compatible with Galaxy Store.
Purpose
PAD is a very useful feature that helps reduce the game's initial download size, as it downloads various game assets at runtime. There are multiple ways of using this feature in Unity games. However, certain PAD configurations may cause the game's assets to fail to load when the game is published to Galaxy Store. In this tutorial, you learn how to properly configure PAD and adjust Unity configurations accordingly, so your game can be successfully published to Galaxy Store.
In the following sections, PAD functionalities are implemented in an existing coin collector game (referenced in the article Integrating Samsung IAP in Your Unity Game), demonstrating how to download and apply a new set of materials for the floor tile at runtime. Here, you also learn about the adjustments that are necessary for successfully publishing a game using PAD to Galaxy Store.
Prerequisites
To follow this tutorial, ensure that your setup has the following:
- Unity Game Engine version 2023.2 or above
- The "Addressables for Android" package for Unity
- A Google Play developer account
- A Galaxy Store Seller Portal commercial seller account
- A game created using Unity where you want to add the PAD features
To implement PAD in your Unity game, you can use the "Addressables for Android" package. This is the easiest and most convenient way to implement PAD in a game. This package is only supported on Unity version 2023.2 or above. If your game is built using a previous version of Unity, please migrate your game to the Unity 2023.2 version first.
PAD implementation considerations
There are multitude of ways to implement PAD in games built with the Unity engine. However, the most common method for implementing PAD restricts the game to being publishable exclusively on the Google Play Store and does not provide any easy method of disabling PAD for uploading these games into other storefronts. For the best experience with your game, it is recommended to use PAD to bundle all game assets together. This approach ensures that all necessary resources are downloaded right away, preventing any missing assets which could affect the user experience.
There are three types of asset packs that can be configured while using PAD: "Install Time," "Fast Follow," and "On Demand." Games that use the "Install Time" asset packs can be uploaded to Galaxy Store without any issues as these assets are installed together with the game and do not require any separate downloads. When Galaxy Store generates a universal APK from AAB files, the "Install Time" assets are directly included in the APK.
Games that are designed to only use "On Demand" or "Fast Follow" asset packs do not allow downloading their assets when they are uploaded to a storefront that is not the Google Play Store. Thus, for any game that uses either the "On Demand" or "Fast Follow" asset pack delivery method, PAD must be disabled in order to upload the game to Galaxy Store.
To ensure that your game's PAD functionality can be easily switched off and your game is successfully uploaded to Galaxy Store, the "Addressables for Android" package must be used to implement PAD.
This article assumes that you have implemented PAD in your game using the "Addressables for Android" package and that you have also configured these two assets with the following configurations:
- A "Grass" asset pack set to be downloaded as a "Fast Follow" asset
- A "Ground" asset pack set to be downloaded as an "On Demand" asset
In the next sections, you learn how to integrate PAD into your existing Unity game using the "Addressables for Android" package so that you can easily publish your game to Galaxy Store with minimal changes.
Basic steps to implement PAD in your Unity game
In this section, you learn how to configure your assets using PAD functionality that keeps your game compatible with both Google Play and Galaxy Store.
- In Unity, configure "Build Settings" to run the game on Android and generate the AAB:
- Click File > Build Settings and then select the Android tab.
- On the "Android" tab, select the Build App Bundle (Google Play) checkbox.
Figure 1: Enabling the "Build App Bundle" option
- Install the "Addressables for Android" package from the Unity Package Manager. This additionally installs the "Addressables" package as a dependency.
- Initialize PAD. Go to Window > Asset Management > Addressables and click Init Play Asset Delivery.
- Configure the "Addressables Groups" for assets:
- Select Window > Asset Management > Addressables > Groups.
- Click New > Play Asset Delivery Assets. This creates a new group.
- Enter a descriptive name. For the purposes of this walkthrough, name one group "Grass" and then create another group and name it "Ground."
Figure 3: Creating asset groups - Assign the assets to the Addressables Group:
- Select the assets you want to assign to an Addressables Group and in the "Inspector" dialog box, tick the Addressable checkbox. The asset is converted into an "Addressable" and assigned to the default Addressables Group.
- Click the folder name in the "Group" field. In the example, the folder name is "Grass."
- Drag and drop the asset from the default group to the group of your choosing. For the purposes of this exercise, assign the grass material related assets to the "Grass" Addressables Group and ground material related assets to the "Ground" Addressables Group.
Figure 4: Converting assets into Addressables
Figure 5: Assigning assets to groups - Select the assets you want to assign to an Addressables Group and in the "Inspector" dialog box, tick the Addressable checkbox. The asset is converted into an "Addressable" and assigned to the default Addressables Group.
- Configure the "Play Asset Delivery" schema for these addressable groups to add the PAD functionality to your game:
- Select any of the top-level Asset Group names in the "Addressables Groups" window to open the inspector window for that group.
- Scroll down in the "Inspector" window until you find the "Play Asset Delivery" schema.
- From the "Delivery Type" dropdown list, select Install Time, Fast Follow, or On Demand, based on your requirements. There is a demonstration below on how the game might behave on Galaxy Store when you choose the option "On Demand." For more information, see the Testing your PAD Enabled Game on the Play Store and Galaxy Store section.
Figure 6: Selecting the delivery type for asset groups - In the "Addressables Groups" dialog box, select Build > New Build > Play Asset Delivery.
Figure 2: "Init Play Asset Delivery" option
Now, the game's addressable-asset configuration is complete. Each asset assigned to an addressable group is packed into an asset pack for that group and the asset pack can be downloaded separately using PAD. Note that asset packs can only be downloaded separately from the Play Store if their delivery type is "On Demand" or "Fast Follow."
Loading and using the addressable assets with AssetReference
This section provides a script which details how to load the addressable assets that were implemented with PAD in the earlier sections. Your game is set up to load the addressable assets efficiently. If an asset has not been downloaded yet, the game automatically attempts to download it as an "On Demand" asset using PAD before it loads into the game.
To complete this setup, use the AssetReference type in your game. This feature enables you to manage and edit addressable assets dynamically at runtime, which gives you more flexibility and control over the assets that your game uses.
To use two game addressable assets in your script, follow these steps:
- Create two
AssetReferenceinstances for the floor types (grass and ground) that you added in the previous section. - Add the
SerializeFieldattribute to theseAssetReferenceinstances. This enables setting up the assets directly from the Unity editor:[SerializeField] AssetReference Grass_mat; [SerializeField] AssetReference Ground_mat;
In the Unity editor, drag and drop the grass and ground assets into the fields in the GameObject script section. Now the AssetReferences specifically reference these two assets during runtime.
Downloading assets during runtime is necessary for PAD. Use AsyncOperations to load these assets:
Grass_mat.LoadAssetAsync<Material>().Completed += OnGrassAssetLoaded;
Ground_mat.LoadAssetAsync<Material>().Completed += OnGroundAssetLoaded;
The OnGrassAssetLoaded and OnGroundAssetLoaded handler functions are defined to use the loaded assets. The LoadAssetAsync method passes the asset using an AsyncOperationHandle, and from there you can access the asset itself using the AsyncOperationHandle.Result parameter.
In this game, we are using PAD to load the grass and ground assets. Once they are successfully loaded, you can change the floor tile material using the following handler functions.
In this example, after loading the grass and ground assets, you apply the material change to all the floor tiles in the level:
void OnGroundAssetLoaded(AsyncOperationHandle<Material> handle)
{
groundMaterial = handle.Result;
foreach (GameObject prefab in floorPrefabs)
{
prefab.GetComponent<MeshRenderer>().material = groundMaterial;
}
}
Save the script and go back to the Unity editor. The new materials are loaded and applied to the floor tiles in the level.
Testing your PAD-enabled game on the Play Store and Galaxy Store
The game configuration for using addressable assets and PAD is complete. Before publishing your game, consider whether to use the "Split Application Binary" option.
- On the Android Player settings, expand "Publishing Settings," and scroll down to the "Split Application Binary" checkbox. This checkbox decides how Unity handles packaging when building the game.
- If this checkbox is checked, Unity splits the base game files from the asset files when building the AAB and enables you to configure each PAD feature in your game. In the images below, you can see what happens when you choose this option.
- If this option is unchecked, Unity always generates a singular archive file and disables PAD. This is the safest option for uploading your game to Galaxy Store, if your PAD configuration is using options that are not supported by Galaxy Store.
- To enable PAD, check the "Split Application Binary" option
- Build the game and upload the generated AAB file to both the Play Store and Galaxy Store to check how the game behaves in both stores.
Figure 7: "Split Application Binary" option
If the game assets load correctly in both stores, the PAD configuration was done correctly. Below is an example of what might happen if "On Demand" configuration is used instead.
When the game is downloaded from the Play Store, Unity automatically downloads the "On Demand" assets. A notification for an "Additional file download" appears during the download process:
Figure 8: Additional file download notification
Once the download is complete, the downloaded asset is loaded in your game, replacing the previous assets. In this example game case, the old ground and grass materials are changed to the new textures configured in the previous section.
Figure 9: Assets updated in the game
However, when the same game AAB file is uploaded to Galaxy Store and a user downloads it from this store, the PAD assets are not downloaded. Thus, when the game tries to use these assets, they cannot be loaded into the game's memory and glitches might appear.
While additional error checking can be done to avoid these glitches, the functionalities which require PAD assets still cannot be used. Internally, the game checks the installation source before trying to download the PAD assets and throws an error if the game is not installed from the Play Store.
Figure 10: Issues might occur if a PAD-enabled game is uploaded to Galaxy Store
Making the game compatible with Galaxy Store
To upload your game to Galaxy Store, you can adjust the asset handling to be compatible with Galaxy Store. The best way to do this is by bundling the assets together with the base game, as explained in the previous sections.
This method is highly recommended. This ensures that the required assets are always available with the game, as well as allowing you to change the assets during runtime, if necessary. Though this can increase the game download size and require you to upload a separate AAB file to Galaxy Store, the process ensures that the assets are always available with the game for full feature parity across all storefronts.
To make your game build compatible with all storefronts, choose one of the following approaches.
Option 1: Uncheck the "Split Application Binary" checkbox
Go to Build Settings > Player Settings > Publishing Settings and uncheck the Split Application Binary checkbox. When you then compile the game, the new AAB file is compatible with Galaxy Store and all the game's functionalities remain intact.
Figure 11: "Split Application Binary" unchecked option.
With this option, the assets are packaged together with the game and no separate download is required.
Option 2: Change delivery type to "Install Time"
If you want to keep using PAD, you can achieve compatibility by changing all addressable asset groups' delivery type to "Install Time." Keep in mind that when choosing this option, all assets need to be changed to "Install Time" one by one, while the previous one is a one-click process. Unlike "On Demand" and "Fast Follow" asset packs, "Install Time" asset packs are included in the universal APK. Thus, the assets are downloaded together with the game and work as intended without causing errors.
From the user's perspective, the main difference between "Install Time" and other PAD options is whether the assets are downloaded when the game is installed or later during gameplay. The initial download size is larger when the assets are packaged together with the game, but on the other hand, the user will not need to wait for the assets to download later during gameplay. This enables offline gameplay as well.
Conclusion
In this tutorial, you have learned how to configure a Unity game with PAD so that it can easily be published to Galaxy Store without requiring massive changes or breaking any compatibility. For more information, check out the "Addressables for Android" package documentation page Build content for Play Asset Delivery. If you have any feedback or questions, reach out to us in the Samsung Developers Forum.
