tencent cloud

This document describes how to configure a Unity project export for the GME APIs for Unity.

Export for iOS

When exporting a Unity project as an Xcode project, you need to process GME dynamic libraries. The processing steps vary by Unity version.

1. Process dynamic libraries (for Unity 2019 or later)

Configuration principle

Create an Editor OnPostprocessBuild script and use the UnityEditor.iOS.Xcode.Extensions.PBXProjectExtensions.AddFileToEmbedFrameworks API, which will automatically copy the dynamic libraries to the framework directory of the final output bundle and sign them.

You can add or remove dynamic libraries based on the required features and determine the list of imported frameworks in the sample code based on the dynamic library list. For more information on dynamic library features, see SDK Version Upgrade Guide.

string[] framework_names = {
    "libgme_fdkaac.framework",
    "libgme_lamemp3.framework",
    "libgme_ogg.framework",
    "libgme_soundtouch.framework"
};

Sample code

You can refer to the add_dylib.cs script file in the demo project and put this part of code in the Editor folder of the project as needed.

[UnityEditor.Callbacks.PostProcessBuild(1002)]
public  static void OnPostprocessBuild (UnityEditor.BuildTarget BuildTarget, string path){  
    if (BuildTarget == UnityEditor.BuildTarget.iOS) {
        UnityEngine.Debug.Log ("OnPostprocessBuild add_dylib:" + path);
#if UNITY_EDITOR_OSX || UNITY_STANDALONE_OSX
        {
            string projPath = UnityEditor.iOS.Xcode.PBXProject.GetPBXProjectPath (path);  
            UnityEditor.iOS.Xcode.PBXProject proj = new UnityEditor.iOS.Xcode.PBXProject ();  

            proj.ReadFromString (System.IO.File.ReadAllText (projPath));  
            // string targetGuid = proj.TargetGuidByName (UnityEditor.iOS.Xcode.PBXProject.GetUnityTargetName ()); // 2018
            string targetGuid = proj.GetUnityMainTargetGuid();    // 2019
                
            // Delete according to the imported frameworks
            string[] framework_names = {
                "libgme_fdkaac.framework",
                "libgme_lamemp3.framework",
                "libgme_ogg.framework",
                "libgme_soundtouch.framework"
            };

            for (int i = 0; i < framework_names.Length; i++)
            {
                string framework_name = framework_names[i];
                string dylibGuid = null;
                dylibGuid = proj.FindFileGuidByProjectPath("Frameworks/Plugins/iOS/" + framework_name);

                if (dylibGuid == null) {
                    UnityEngine.Debug.LogWarning (framework_name + " guid not found");
                } else {
                    UnityEngine.Debug.LogWarning (framework_name + " guid:" + dylibGuid);
                    // proj.AddDynamicFramework (targetGuid, dylibGuid);
                    UnityEditor.iOS.Xcode.Extensions.PBXProjectExtensions.AddFileToEmbedFrameworks(proj, targetGuid, dylibGuid);

                    proj.AddBuildProperty(targetGuid, "LD_RUNPATH_SEARCH_PATHS", "@executable_path/Frameworks");
                    System.IO.File.WriteAllText (projPath, proj.WriteToString ());
                }
            }
        }
#endif
    }
}

2. Process dynamic libraries (for Unity versions earlier than 2019)

Currently, only Unity 2019 or later can use UnityEditor.iOS.Xcode.Extensions. You can export the UnityEditor.iOS.Xcode package from a later version for use in an earlier version, or directly decompress the attachment UnityEditorAV.iOS.XCode.zip and place it in the Editor folder of the project directory.

3. Export the Xcode project

Make sure that the Xcode version is 10.0 or later. Export the Xcode project from the Unity Editor.

4. Disable Bitcode

If the following error occurs during the compilation, disable Bitcode. Search for Bitcode in Targets > Build Settings and set the corresponding option to NO.

5. Add access to iOS

• Required background modes: Allows running in the background (optional).
• Microphone Usage Description: Allows access to microphone.

6. Add library files

If the following error occurs during compilation, please complete the library files.

The list of library files is as follows:

libc++.tbd
CoreMedia.framework
libresolv.tbd
AVFoundation.framework
Security.framework
CoreAudio.framework
AudioToolbox.framework
libiconv.tbd
libz.tbd
SystemConfiguration.framework
OpenAL.framework

7. Add libresolv9.tbd

If the following error occurs:

Add libresolv9.tbd to UnityFramework.

8. FAQs about export

If you have any questions during exporting, see Exporting for iOS.

Export for Android

1. Delete unnecessary .lib files

The GME SDK for Unity provides lib files for arm64-v8a, armeabi-v7a, and x86 by default. Please delete unnecessary files as needed.

Architecture loss

A crash will occur if the exported Android executable file lacks the specified architecture.

2. Configure permissions

2.1 Required permissions
Add the following permissions in the AndroidManifest.xml file of the project:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

2.2 Adding permissions as needed
Add the following permissions in the AndroidManifest.xml file of the project as needed:

 <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

3. FAQs about export

If you have any questions during exporting, see Exporting for Android.

Export for Windows

If you have any questions during exporting, see Exporting for Windows.

Export for WebGL

1. Configure WebGL plugins

Set the scope of gmesdk.dll on Windows to prevent it from conflicting with gmesdk on WebGL.

2. Disable Flare Layer (on Unity 2018 or later)

As certain Unity versions no longer support the Flare Layer mode in MainCamera, you need to deselect Flare Layer in the scene to be built; otherwise, the following error will be reported:

3. Select a template

When exporting to WebGL, select a WebGL template of GME to ensure that the relevant dependent libraries are imported to the build. The project will use the GMEWebGLTemplatesUnity2018 template by default, which supports Unity 2018 and 2019. For Unity 2020 and 2021, you need to use GMEWebGLTemplatesUnity2021 to create the build.

4. Import frontend libraries

Before importing GME for WebGL to your project, you need to manually import frontend libraries, place the library files in the corresponding import locations, and add the audio tag as shown below. If you want the above operations to be automatically completed every time you build a Unity project, you can add the corresponding template to your project by referring to the GME demo for WebGL.

5. FAQs about export

If you have any questions during export, see Program Export.