Créer sa première bibliothèque Android pour Unity

Jonathan Odul

Aujourd'hui, Unity permet gratuitement l'exportation de vos projets sur les plates-formes Android et iOS. Unity comprend déjà un large éventail d'outils permettant de gérer et d'accéder directement à certaines fonctions de votre smartphone (caméra, gyroscope…). Cependant, il est probable que dans votre projet, vous avez besoin d'utiliser un composant qui n'est pas géré nativement par Unity (par exemple, utiliser le système de notification sur Android). Pour cela, vous aurez recours à la création de plugins.

Dans cet article, nous allons voir comment créer, ajouter et utiliser une bibliothèque JAR pour la plate-forme Android à un projet Unity.

Commentez

- Titre : Créer sa première bibliothèque Android pour Unity

- Auteur : Jonathan Odul

- Parution : 9 juin 2013

- Licence : Copyright ® 2013 Jonathan Odul. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Prérequis

- II. Projet Android

- III. Projet Unity

- IV. Allez plus loin

- IV-A. Surcharger la classe Activity par défaut

- V. Remerciements

I - Prérequis

Avant de commencer sur ce tutoriel, je suppose que vous êtes déjà en possession de ces différents éléments sur votre ordinateur :

- Unity ;

- Eclipse + ADT.

Pour rappel, afin qu'un projet Unity fonctionne sur votre terminal Android, ce dernier doit posséder la configuration minimale suivante :

- Android OS 2.0 ou plus ;

- ARMv7 (Cortex family) ;

- CPU GPU avec support OpenGLES 2.0 est recommandé.

Plus d'informations :
http://unity3d.com/unity/system-requirements.

Dans notre exemple, nous allons voir comment créer une bibliothèque Android et l'utiliser à l'intérieur d'un projet Unity. Nous allons simplement créer une classe Java contenant une fonction statique écrivant dans les logs du smartphone. Ensuite, nous verrons comment appeler cette méthode depuis un projet Unity.

II - Projet Android

La première chose à faire est de tout d'abord créer un projet Android dans Eclipse.
Utilisez le même SDK que vous comptez utiliser lors de la génération de votre projet Unity par la suite.

Dans la suite, pas besoin de créer une icône, ni même de générer une Activity pour votre application : Unity le générera automatiquement pour vous. Cependant, très important, pensez à marquer le projet comme étant une bibliothèque.

Ensuite, commençons par créer un package que, pour l'exemple, je nomme « com.jidul.unity_plugin », et enfin créons à l'intérieur de ce dernier une classe appelée « UnityLog ».

Dans cette classe, nous allons ajouter une simple méthode qui prend en paramètre une variable de type String correspondant au message que l'on souhaite afficher dans les logs.
Voici le code :

package com.jidul.unity_plugin;

import android.util.Log;

public class UnityLog {
public static void trace(String message) {
Log.d("UnityAndroidPlugin", message);
}
}

Notre simple bibliothèque Android est d'ores et déjà prête.
Pour la récupérer, il suffit de récupérer le fichier *.jar généré dans le dossier bin du projet.

III - Projet Unity

Il est maintenant temps de passer à la partie Unity. Avant de continuer, un projet doit être auparavant créé.

Pensez bien d'abord à vérifier que vous avez bien indiqué à Unity la location du SDK Android. Pour cela, allez dans « Edit », « Preferences… » puis « External Tool ».

Ensuite, ajoutons la bibliothèque Android au projet. Créez tout d'abord le dossier« Plugins » dans les Assets, puis un dossier « Android » à l'intérieur de celui-ci. Enfin, copiez-y le fichier jar généré auparavant dans Eclipse.

Concernant le fichier AndroidManifest, Unity vous en crée un lors de la génération de votre application. Cependant, il peut arriver que vous ayez besoin d'utiliser votre AndroidManifest personnel (par exemple pour la définition de certains paramètres ou permissions). Pour cela, trouvez le fichier AndroidManifest par défaut de Unity dans ce répertoire (valable pour Windows) : C:\Program Files\Unity\Editor\Data\PlaybackEngines\androiddevelopmentplayer ; ensuite, copiez-le dans le même répertoire Android du projet Unity. À partir de là, vous pouvez éditer à votre guise le fichier Manifest du projet.

Une fois copié dans le dossier du plugin, vous pouvez éditer ce fichier Manifest qui sera automatiquement utilisé lors de la génération de votre projet Unity sous Android.

Maintenant, nous allons créer un simple bouton sur la scène qui fait que lorsqu'on cliquera dessus, cela appellera notre fonction de notre plugin Android.

Créez un dossier nommé « Scripts » dans les Assets et créez un nouveau « Script C# » nommé Button.cs. Ouvrez ensuite ce fichier script.

using UnityEngine;
using System.Collections;

public class GUITest : MonoBehaviour {

void OnGUI () {
GUI.Box(new Rect(10,10,100,90), "JiDuL Android Plugin");

if(GUI.Button(new Rect(20,40,80,20), "Log")) {
AndroidJavaClass jc = new AndroidJavaClass("com.jidul.unity_plugin.UnityLog");
String message = "It looks like a bird, but it's not a bird.";
jc.CallStatic("trace", message);
}
}
}

Explication :

AndroidJavaClass jc = new AndroidJavaClass("com.jidul.unity_plugin.UnityLog");

On récupère une instance de notre classe en passant le nom du package puis le nom de la classe en paramètre.

jc.CallStatic("trace", "It looks like a bird, but it's not a bird.");

On appelle ensuite la méthode static de cette classe en passant en paramètre le nom de la méthode, et son argument.

Cet exemple décrit un cas d'utilisation très simple, mais vous pouvez bien entendu récupérer la valeur de retour d'une méthode, instancier des objets et utiliser des méthodes non statiques, ainsi que de manipuler des objets complexes Java depuis un script Unity. Vous trouverez plus d'informations et de détails sur cette page :
http://docs.unity3d.com/Documentation/Manual/PluginsForAndroid.html.

Pour finir, on crée un simple GameObject sur la scène, et on attache ce script dessus. Rien de plus simple. Il n'a plus qu'à générer l'APK et tester sur un votre appareil Android. Voici le résultat attendu :

IV - Allez plus loin

IV-A - Surcharger la classe Activity par défaut

Lors de la génération de votre projet Android sous Unity, ce dernier utilisera une Activity (UnityPlayerActivity) qui instanciera le player Unity dans votre application.
Vous pouvez trouver les sources de cette classe dans le répertoire :

- /Applications/Unity/Unity.app/Contents/PlaybackEngines/AndroidPlayer/src/com/unity3d/player sous MAC ;

- C:\Program Files\Unity\Editor\Data\PlaybackEngines\androidplayer\src\com\unity3d\player sous Window.

Pas besoin d'importer les sources, mais simplement la bibliothèque JAR « classes.jar » dans votre bibliothèque Android créée précédemment.
Vous pouvez trouver cette bibliothèque dans le répertoire :

- /Applications/Unity/Unity.app/Contents/PlaybackEngines/AndroidPlayer/bin sous MAC ;

- C:\Program Files\Unity\Editor\Data\PlaybackEngines\androidplayer\bin sous Window.

Ensuite, dans votre projet Android, créez une nouvelle classe et faites-la hériter de la classe UnityPlayerActivity. À partir de là, vous pouvez ensuite ajouter des composants ou de nouvelles fonctions à votre Activity. Lorsque tout est prêt, exportez votre Activity en bibliothèque JAR comme au début de ce tutoriel et ajoutez-la à votre projet Unity. Maintenant, il ne vous reste plus qu'à surcharger et éditer le fichier AndroidManifest.xml pour mettre votre Activity comme Activity par défaut de lancement.

Une autre solution est de créer une Activity vierge et d'y ajouter le composant UnityPlayer présent dans la bibliothèque « classes.jar ». Vous pouvez jeter un œil aux sources de la classe UnityPlayerActivity pour comprendre comment cette chose est réalisée.

Enfin, n'hésitez pas à visiter la documentation officielle pour plus d'informations :
http://docs.unity3d.com/Documentation/Manual/PluginsForAndroid.html.

V - Remerciements

Je tiens particulièrement à remercier ClaudeLELOUP pour sa patience et relecture attentive, Feanorin et MrDuChnok pour leur relecture technique, ainsi que Max pour son aide précieuse.