Réduire et optimiser le code Unreal Engine avec R8

Bien que la logique de base de votre jeu dans Unreal Engine soit écrite en C++ ou en Blueprints, l'empaquetage Android compile le bytecode Java et Kotlin (classes.dex) pour gérer les événements de cycle de vie GameActivity, les services Google Play, la facturation, l'audio et les plug-ins d'analyse.

R8, l'outil de minification et d'optimisation du code par défaut du plug-in Android Gradle (AGP), supprime les classes et les méthodes inutilisées, et optimise le bytecode. Cela permet non seulement de réduire la taille de téléchargement de votre package, mais aussi l'espace mémoire utilisé par les pages DEX mappées en mémoire (mmap) et la surcharge du processus Java de référence, ce qui réduit la pression sur la mémoire physique et les arrêts par le tueur de mémoire faible (LMK). Google Play surveille également les niveaux d'optimisation DEX de votre jeu grâce à la métrique Optimisation du code DEX dans Android Vitals.

Comportement par défaut et compatibilité avec les versions d'Unreal Engine

À partir de la version 4.22.0, l'outil UEDeployAndroid.cs d'Unreal Engine injecte par défaut minifyEnabled true dans la configuration de compilation de la version Android générée (buildAdditions.gradle). Comme UE 4.25 a mis à niveau la chaîne d'outils groupée vers AGP 4.0.0, R8 est activé par défaut (true) sur toutes les versions de build (livraison et distribution) dans UE 4.25 et versions ultérieures sans configuration supplémentaire.

Différences entre les builds de version et de débogage

UnrealBuildTool (UEDeployAndroid.cs) configure le fichier buildAdditions.gradle généré différemment pour les builds de version et les versions de débogage :

buildTypes {
    release {
        signingConfig signingConfigs.release
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
    debug {
        debuggable true
        signingConfig signingConfigs.debug
    }
}

• Release (livraison ou distribution) : définit minifyEnabled true et applique proguard-rules.pro par défaut, en exécutant la minification de code et l'obscurcissement du code R8.
• Débogage (développement) : active debuggable true et omet minifyEnabled (par défaut, false) pour préserver l'itération de compilation rapide et le débogage des symboles.

Ajouter des règles de conservation à l'aide d'UPL (Unreal Plugin Language)

Comme R8 s'exécute automatiquement sur les builds de version dans UE 4.25 et versions ultérieures, vous devez conserver les classes Java accessibles uniquement via JNI C++ (JNIEnv->FindClass, GetMethodID) ou le fichier manifeste. Les classes sans sites d'appel Java sont traitées comme inutilisées et supprimées par R8, ce qui peut entraîner l'échec des fonctionnalités qui fonctionnent dans les builds de développement avec ClassNotFoundException ou NoSuchMethodError dans les builds de livraison.

Utilisez la balise <proguardAdditions> dans un fichier XML Unreal Plugin Language (UPL) pour fusionner les règles de conservation personnalisées dans proguard-rules.pro lors de l'empaquetage. Ajoutez le bloc suivant au fichier *_UPL.xml de votre projet ou de votre plug-in :

<root xmlns:android="http://schemas.android.com/apk/res/android">
    <proguardAdditions>
        <insert>
            -keep class com.epicgames.unreal.** { *; }
            -keep class com.example.plugin.** { public *; }
            -dontwarn com.example.plugin.**
        </insert>
    </proguardAdditions>
</root>

Résoudre les problèmes courants

Cette section explique comment résoudre les problèmes courants de packaging et d'exécution lors de l'utilisation de R8 dans Unreal Engine.

Désactiver temporairement R8 pour le débogage

Pour déterminer si un plantage qui ne se produit que dans la version de production est dû à la suppression de classes requises par R8, insérez DISABLE_MINIFY=1 sous <gradleProperties> dans votre fichier UPL. Lorsqu'il est présent, UEDeployAndroid.cs génère minifyEnabled false :

<gradleProperties>
    <insert>
        DISABLE_MINIFY=1
    </insert>
</gradleProperties>

Missing classes detected while running R8 erreur de packaging

Dans UE 5.4 et versions ultérieures (AGP 7.4.2+), R8 applique des vérifications strictes des classes manquantes. Si l'empaquetage échoue avec cette erreur, inspectez missing_rules.txt dans votre répertoire de compilation intermédiaire (sous Intermediate/Android/.../gradle/app/build/outputs/mapping/release/missing_rules.txt) et ajoutez les dépendances de bibliothèque manquantes ou les règles requises à <proguardAdditions> dans votre fichier UPL.

Compatibilité du mode complet R8 avec les SDK tiers

Dans UE 5.8 et versions ultérieures (AGP 8.13.0+), le mode complet de R8 est activé par défaut pour effectuer des optimisations plus agressives. Si un ancien SDK Android tiers échoue lors de l'exécution en raison de problèmes de réflexion, mettez à jour les règles ProGuard du plug-in ou rétablissez le mode de compatibilité de R8 en ajoutant la propriété suivante à votre fichier UPL :

<gradleProperties>
    <insert>
        android.enableR8.fullMode=false
    </insert>
</gradleProperties>