Assets

Using Assets in IRMGARD

With the introduction of expansion files, the Assets used in IRMGARD need to be relocated and accessed differently within the application.

• Assets location
• Accessing Assets
• Generate Expansion Files
• Test Expansion Files

Assets location

Assets in IRMGARD are located in the two directories Assets and MainAssets.

MainAssets contains a set of immutable asset files that are included in the main expansion file main.XXX.de.kopfhandundfuss.irmgard.obb during the build. In the context of the continuous development of IRMGARD it is discouraged to store new files in MainAssets.

Whereas directory Assets contains all newly added assets and is the standard location for new assets. During the build the content of this directory is included in the patch expansion file patch.XXX.de.kopfhandundfuss.irmgard.obb.

After the completion of a new level with a larger number of new media files, these files can be moved from the directory Assets into MainAssets. However, only files that do not change in the future should be moved to MainAssets. For example *.json configuration files do frequently change and should not be outsourced to MainAssets.

Accessing Assets

Instead of the usual access via Android.Content.Res.AssetManager (ctx.Assets.Open(string filename)), it is now required to only use methods of the helper class AssetHelper for accessing assets.

The methods of the class AssetHelper are modeled to the currently used methods of the AssetManager interface.

The AssetHelper class - according to the setting of the flag Env.UseOBB - enables the transparent access to the assets regardless of whether they reside in one of the expansion files or directly in the APK.

Generate Expansion Files

The use and generation of the expansion files is controlled by the two properties Env.UseOBB and <ZipAssets>.

Property Env.UseOBB

If expansion files should be used, the constant UseOBB of helper class Env must be set to true. For Release builds this value should always be left to true. For Debug builds this value should be false for testing during development. To test access to media files within expansion files this value can be set to true for Debug builds also.

Property <ZipAssets>

The constant Env.UseOBB is required to switch between expansion files (Opaque Binary Blobs - OBBs) and APK within the app.

The actual generation of the two expansion files is controlled via the flag <ZipAssets> in the first PropertyGroup of the build file IRMGARD.csproj.

• The setting <ZipAssets>1</ZipAssets> generates the two expansion files main.XXX.de.kopfhandundfuss.irmgard.obb and patch.XXX.de.kopfhandundfuss.irmgard.obb into folder IRMGARD/IRMGARD. The version numbers (XXX) for the OBB files are read from the metadata properties obbMainVersionCode and obbPatchVersionCode of the application from the configuration file AndroidManifest.xml. In the generated APK the folder assets within the APK is left empty. Both expansion files are zipped uncompressed (ZipLevel="0"), because Android.Media.MediaPlayer can not access compressed files inside the zip.
• <ZipAssets>0</ZipAssets> prevents the generation of the expansion files and puts the assets from the project folders MainAssets and Assets together into the destination folder assets of the APK.

Test Expansion Files

This applies only to non-rooted devices (only tested this on real devices / not on emulators)

• OBB files are located in [shared-storage]/Android/obb/[package-name]
  • [shared-storage]: available from Environment.ExternalStorageDirectory (e.g. /storage/emulated/0 or /storage/sdcard0)
  • [package-name]: de.kopfhandundfuss.irmgard
• Make sure the IRMGARD specific directory for example adb shell "ls -l /storage/emulated/0/Android/obb/de.kopfhandundfuss.irmgard" exists
• Create directory if not exists: adb shell "mkdir /storage/emulated/0/Android/obb/de.kopfhandundfuss.irmgard"
• After generating both OBB files via a Debug Build (Env.UseOBB=true / ZipAssets set to 1) you have to push both files to the device
  • adb -d push -p [Project-Dir]\IRMGARD\IRMGARD\main.11.de.kopfhandundfuss.irmgard.obb /storage/emulated/0/Android/obb/de.kopfhandundfuss.irmgard
  • adb -d push -p [Project-Dir]\IRMGARD\IRMGARD\patch.11.de.kopfhandundfuss.irmgard.obb /storage/emulated/0/Android/obb/de.kopfhandundfuss.irmgard
• Note: Uninstalling the app automatically removes the IRMGARD specific obb/de.kopfhandundfuss.irmgard directory!