Configurer Android pour l'Unreal Engine
Pour empaqueter correctement le service ASIS (Android Single Instance Service), vous devez configurer les SDK et NDK Android. L'Unreal Engine (UE) utilise Android Studio et les outils de ligne de commande du SDK Android pour télécharger et installer les composants SDK Android nécessaires au développement de projets Android. Consultez la documentation suivante :
Si vous utilisez Unreal Engine 5.5.x, activez les plateformes SDK et les outils suivants :
Créer un projet à partir d'un modèle
Une fois les SDK/NDK Android installés, nous pouvons configurer le plug-in de modèle ASIS. Le plug-in est fourni dans un fichier d'archive distinct. Des étapes manuelles doivent donc être effectuées pour préparer le code source de l'UE.
Obtenir le code source de l'UE5.*
Récupérer la dernière version du code source depuis la branche principale de l'UE5 (Perforce ou GitHub)
Perforce :
Accéder à l'Unreal Engine avec Perforce
GitHub :
Configurer le plug-in ASIS
Si vous utilisez Perforce :
Accédez au dossier du plug-in ASIS :
UE5_Main\Engine\Restricted\NotForLicensees\Plugins\Android SingleService.Dans le dossier
Android SingleInstanceService,ouvrez le dossierTemplates:UE5_Main/Engine\Restricted\NotForLicensees\Plugins\Android SingleInstanceService\Templates\.
Si vous utilisez GitHub :
Décompressez l'archive fournie par Epic et copiez le contenu du plug-in ASIS sous Engine\Restricted\NotForLicensees\Plugins\AndroidSingleInstanceService.
Copier le modèle
Copiez le dossier TP_HMI_ASIS sous UE5/Templates/.
Puis, copiez le code suivant dans le fichier UE5_Main/Templates/TemplateCategories.ini.
Categories=(Key="HMI", LocalizedDisplayNames=((Language="en",Text="Automotive\nHMI &\nVehicle Cockpit using Android Single Instance Service")), LocalizedDescriptions=((Language="en",Text="Find templates for automotive vehicle cockpit using Android Single Instance Service"), Icon="TP_HMI_ASIS/Media/AutomotiveHMI_2x.png", IsMajorCategory=true)Exécutez UnrealEditor. Le nouveau modèle IHM devrait maintenant s'afficher à l'ouverture du navigateur de projets Unreal Engine :
Créer un projet à partir du modèle IHM
Le projet devrait ressembler à ce qui suit :
Ajouter le plug-in ASIS à un projet existant
Si vous devez ajouter ASIS à un projet existant, procédez comme suit :
Activer ASIS dans les paramètres du plug-in
Ajoutez le répertoire du plug-in de remappage. Ajouter le code suivant au fichier {ProjectName}/Config/DefaultGame.ini.
C++[Staging] +RemapDirectories=(From="Engine/Restricted/NotForLicensees/Plugins/AndroidSingleInstanceService", To="Engine/Plugins/Runtime/AndroidSingleInstanceService") +RemapDirectories=(From="Engine/Restricted/NotForLicensees/Plugins/Experimental/MultiWindow", To="Engine/Plugins/Experimental/MultiWindow")Ouvrez votre projet et activez les paramètres du plug-in ASIS suivants.
Exemple d'empaquetage et d'exécution d'ASIS
Avec le SDK Android et le modèle configuré dans l'Unreal Engine, nous pouvons maintenant empaqueter le projet en tant qu'application Android :
Communication de l'application
Après avoir empaqueté l'application depuis l'Unreal Engine, nous allons utiliser un exemple d'application cliente pour communiquer avec l'APK Unreal Engine.
Le paquet Unreal Engine contiendra 3 artefacts.
Un APK avec Android Service. Il figure dans le dossier que vous avez sélectionné dans la boîte de dialogue Empaqueter le projet.
Des bibliothèques d'aide ASIS utilisées dans les applications clientes.
C++Binaries/Android/aars ├── asisclientlib-1.0.1-debug.aar ├── asisclientlib-1.0.1-debug.jar ├── asiscommon-1.0.1-debug.aarUn exemple d'application cliente qui communique avec le service. Il n'est PAS situé dans le projet Unreal Engine empaqueté, mais sous le dossier Binaries de votre Projet Unreal Engine. L'emplacement est le suivant : Unreal Projects\*Nom_Projet*\Binaries\Android.
Vous pouvez utiliser Android Studio pour ouvrir le projet Android. Le processus de compilation Android sera automatiquement lancé lors de son ouverture.
Vous pouvez aussi utiliser une ligne de commande
pour générer un APK client.
cd {Project_Name}\Binaries\Android\ExampleUseCase_{Project_Name}\
gradlew assembleDebugL'APK sera généré à l'emplacement suivant :
{Project_Name}\Binaries\Android\ExampleUseCase_{Project_Name}\app\build\outputs\apk\debug\app-debug.apk.
Après avoir sélectionné un appareil Android, revenez dans Android Studio et exécutez l'application en appuyant sur Maj + F10 ou en cliquant sur le bouton vert Play dans la barre de menus supérieure.
Après le service d'installation
À présent, installez les applications d'exécution de l'APK Unreal Engine sur votre appareil. Vous pouvez utiliser ligne de commande dans le dossier du paquet Unreal Engine pour exécuter la commande adb.
Dans l'application Android, sélectionnez Activer la vue 1, la vue 2 et la vue 3 pour afficher le service Android communiquant avec l'application Unreal Engine
Activer le mode multifenêtre
Le mode multifenêtre fonctionne à partir de la version 5.6 de l'UE. Pour activer le mode multifenêtre, le plug-in AndroidSingleInstanceService est requis. Une fois les étapes précédentes effectuées pour activer ASIS, vous pouvez commencer ici.
Activez le plug-in Multiview dans les paramètres du plug-in.
Créez deux caméras dans le niveau pour tester le mode multifenêtre. Le modèle TP_HMI_Automotive sera utilisé pour cet exemple.
Ensuite, ouvrez le blueprint du niveau. Ajoutez des acteurs de caméra aux blueprints. Faites glisser le nœud Camera Actor et sélectionnez ‘Obtenir la vue de caméra’. Puis, supprimez le nœud Get Camera. Seule la référence de l'objet de composant de caméra est nécessaire.
Créez ensuite le nœud Register Camera pour Asis. Connectez le nœud de l'objet caméra aux nœuds correspondants. Assurez-vous de définir l'identifiant sur 1 et 2 pour chaque caméra. Connectez les broches d'exécution à Event Begin Play.
Empaquetez le projet pour Android.
Ouvrons maintenant l'application cliente dans Android Studio. Ouvrez l'exemple de projet d'application cliente Android. Il n'est PAS situé dans le projet Unreal Engine empaqueté, mais sous le dossier Binaries de votre Projet Unreal Engine. Voici l'emplacement du code du cours pour l'application cliente :
{Project_Name}\Binaries\Android\ExampleUseCase_{Project_Name}\
Ensuite, passez du mode standard ASIS au mode MultiviewEdit.
Modifiez Binaries\Android\ExampleUseCase_{Project_Name}\app\src\main\AndroidManifest.xml. Remplacez l'activité de jeu par ActivityForMultiView à la ligne 22.
Dans Android Studio et avec un appareil Android connecté, vous pouvez lancer l'application en appuyant sur Maj+F10 ou en sélectionnant le bouton vert Play dans le menu supérieur.
Après le service d'installation
À présent, installez les applications d'exécution de l'APK Unreal Engine sur votre appareil. Vous pouvez utiliser ligne de commande dans le dossier du paquet Unreal Engine pour exécuter la commande adb.
Sélectionnez les options Joindre/dissocier la vue 1 et Joindre/dissocier la vue 2 pour afficher les caméras. ASIS et le mode multifenêtre fonctionne maintenant sur Android.
Aperçu de l'architecture
Approches prises en charge
Description de l'interface
Classe ASICConnection
Cette classe permet d'établir une connexion et de communiquer avec un service ASIS. Elle encapsule les complexités de cette communication et fournit une interface facile à utiliser pour envoyer et recevoir des données et des commandes.
L'interface ASICConnection.ASICConnectionCallBacks définit des rappels pour les événements ASICConnection. Implémentez cette interface lorsque vous voulez gérer les événements de confirmation de connexion.
public interface ASISConnectionCallBacks
{
void onConnectionSuccess();
void onServiceDisconnected();
}
onConnectionSuccess() : est appelé lorsque la connexion au service a été correctement établie.
onServiceDisconnected() : est appelé lorsqu'une connexion au service est perdue.
L'interface ASICConnection.EngineMessagesListener définit un auditeur pour les messages du moteur. Implémentez cette interface pour gérer les messages du moteur.
public interface EngineMessagesListener
{
void onEngineMessage(Message message);
}
onEngineMessage(Message message) : est appelé lorsqu'un message est envoyé par le moteur.
Message : valeurs du message entrant
Classe ASICConnection.ConnectionBuilder
Cette classe implémente le modèle de conception du constructeur pour créer des instances de ASICConnection. Elle applique un style fluide permettant de relier des méthodes, ce qui améliore la lisibilité lorsque plusieurs paramètres sont requis.
ConnectionBuilder(Context ctx)Elle initialise une nouvelle instance de la classe `ConnectionBuilder`en utilisant le contexte donné.
Paramètres
ctx: le contexte dans lequel créer le ConnectionBuilder.
public ConnectionBuilder withConnectionListener(ASISConnectionCallBacks connectionListener)Définit l'auditeur ASICConnectionCallBacks pour l'ASICConnection.
Paramètres
connexionListener: l'auditeur ASICConnectionCallBacks à définir.
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withEngineMessageListener(EngineMessagesListener engineMessageListener)Définit l'EngineMessagesListener pour l'ASICConnection.
Paramètres
engineMessageListener: l'auditeur EngineMessageListener à définir.
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withConnectionId(String connectionID)Définit le connectionID pour l'ASICConnection.
Paramètres
connectionID: chaîne contenant l'identifiant de connexion
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withServicePackageName(String packageName)Remplacer le nom du paquet de service par défaut
Paramètres
packageName: nom du paquet de service (com.epicgames.PROJECTNAME)
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withServiceClassName(String className)Remplacer le nom de la classe de service par défaut
Paramètres
className: nom de la classe de service (com.epicgames.makeaar.UnrealSharedInstanceService)
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withObbModuleName(String obbModuleName)Remplacer l'obbModuleName par défaut
Paramètres
obbModuleName : nom obb de contenu (nom de projet UE)
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withInsightsTracing()Activer InsightsTracing
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withCommandLineArgs(String cmdArgs)Remplacer les arguments de la ligne de commande par défaut
Paramètres
cmdArgs : argument de ligne de commande pour démarrer l'UE
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ConnectionBuilder withOverridePropagateAlpha(boolean value)Remplacer la valeur alpha de propagation mobile par défaut
Paramètres
value: remplacer la valeur alpha de propagation mobile par défaut
Renvoie
L'instance de ConnectionBuilder, qui permet de relier des méthodes.
public ASISConnection build()Crée une instance ASISConnection à l'aide des paramètres définis.
Renvoie
Une nouvelle instance ASICConnection.
Exemple :
public class UseServiceActivity extends Activity
implements ASISConnection.ASISConnectionCallBacks,
ASISConnection.EngineMessagesListener
....
ASISConnection mServiceConnection ;
...
mServiceConnection = new ASISConnection.ConnectionBuilder(this) .withServicePackageName("com.epicgames.UE_PROJECT")
.withObbModuleName("UE_PROJECT")
.withConnectionListener(this)
ASISConnection(ConnectionBuilder builder)Constructeur qui accepte un élément ConnectionBuilder comme argument.ConnectionBuilder
Ce constructeur est généralement utilisé par le biais de la méthode build() du ConnectionBuilder.
public boolean bindToUnrealInstanceService()Se lie à un service d'instance unique Unreal pour Android par l'appelant donné.
Renvoie
Renvoie
truesi la liaison a réussi, sinon false.
public void unbindToUnrealInstanceService()Se dissocie du service d'instance Unreal.
public boolean isBoundToService()Vérifie si l'application est actuellement liée au service.
Renvoie
Cette méthode renvoie true si l'application est liée au service.
public int attachSurfaceToService(int displayIndex, Surface externalSurface)Joint une surface externe au service pour le rendu.
Paramètres :
displayIndex : l'index de l'affichage, la valeur 0 indiquant un affichage unique.
externeSurface : la surface à attacher.
Renvoie :
l'identifiant de la surface jointe.
public boolean detachSurfaceFromService(int attachId, Handler.Callback callback)Disjoint une surface du service en y associant un identifiant.
Paramètres :
attachId : l'identifiant de la jonction pour disjoindre la surface.
callback : une fonction de rappel qui est appelée lorsque la disjonction est terminée.
Renvoie
Renvoie true si la disjonction a été correctement lancée, sinon false.
public boolean sendData(String key, Object value)Cette méthode permet d'envoyer des données de clé-valeur au service ASIS.
Paramètres
key : une chaîne qui représente la clé des données envoyées.
value : l'ensemble de données à envoyer.
Renvoie
Cette méthode renvoie une valeur booléenne qui indique si les données ont été correctement envoyées.
public boolean consoleCommand(String consoleCommand)Envoie une commande de console au service connecté.
Paramètres
consoleCommand : une chaîne contenant une commande de console.
Renvoie
Renvoie true si le message a été correctement envoyé.
public boolean sendTouchEvent(MotionEvent event, int attachId)Transmettre un événement tactile au service à partir des surfaces jointes.
Paramètres
event : MotionEvent Android représentant l'événement tactile.
attachId : l'identifiant associé à la surface.
Renvoie
Renvoie true si l'événement tactile a été correctement envoyé, sinon false.
Intégration de l'application Android
Importez des bibliothèques Java ASIS dans votre projet.
Copiez les bibliothèques générées depuis {Project_Name}\Binaries\Android\aars dans l'espace de votre application (par ex. : libs).
{Android_app}/libs
├── asisclientlib-1.0.1-debug.aar
├── asisclientlib-1.0.1-debug.jar
├── asiscommon-1.0.1-debug.aar
└── asiscommon-1.0.1-debug.jar
Ajouter l'importation au journal via build.gradle
android {
...
repositories {
flatDir { dirs 'libs' }
}
...
}
def asiscommonVersion = "1.0.1"
def asisclientlibVersion = "1.0.1"
Le diagramme de séquence du cycle de vie d'une activité d'application :