games/crates/apps/game-snake-poc-tauri/USAGE.md

Utilisation — Snake Tauri Android

Prérequis locaux

Le host utilise Cargo/Rust, cargo tauri, Node/npm, wasm-bindgen, Java et le SDK Android. Le dépôt attend ANDROID_HOME vers le SDK Android et des NDK side-by-side sous $ANDROID_HOME/ndk/<version>.

NDK_HOME n'est pas un prérequis utilisateur du projet. Tauri sélectionne la version NDK side-by-side appropriée sous $ANDROID_HOME/ndk/<version> et peut injecter lui-même NDK_HOME dans ses sous-processus Android. Une variable globale ne doit donc pas être ajoutée uniquement pour satisfaire la documentation générique de Tauri.

Pour 0.3.1, le JDK Android de référence est JDK 17. Le template Tauri 2.11.x utilisé par le projet génère Gradle 8.14.3 avec Android Gradle Plugin 8.11.0 : AGP 8.11 exige au minimum JDK 17 et Gradle 8.14.x ne peut pas s'exécuter sur Java 25. JDK 17 fournit donc la baseline reproductible commune aux deux contraintes.

Le Java 25 global de la machine de validation peut rester installé. En revanche, le JBR de l'Android Studio actuellement installé est lui aussi Java 25 et ne doit donc pas être utilisé pour cette gate malgré la recommandation générique de Tauri d'utiliser le JBR d'Android Studio. Le Gradle global installé sur la machine n'est pas utilisé par gen/android/gradlew et n'est pas un prérequis du projet.

Avant une commande Tauri Android, sélectionner explicitement un JDK 17 installé et vérifier la version :

export JAVA_HOME=/chemin/vers/jdk-17
"$JAVA_HOME/bin/java" -version

Ne pas modifier gen/android pour contourner une incompatibilité de JDK.

Pour les cibles actuellement disponibles, aarch64-linux-android permet le smoke sur l'appareil ARM64 et x86_64-linux-android celui des AVD x86_64. Les autres ABI restent disponibles pour les validations multi-ABI ultérieures mais ne sont pas nécessaires au smoke courant.

Initialisation locale

Installer les dépendances frontend dans la crate :

(cd crates/apps/game-snake-poc-tauri && npm install)

Initialiser une fois le projet Android généré par Tauri :

(cd crates/apps/game-snake-poc-tauri && cargo tauri android init)

Le répertoire gen/ produit par Tauri est généré et ignoré ; il n'appartient pas aux deltas et ne doit pas être patché par des scripts propres au jeu.

Si ce répertoire a été créé ou modifié par 0-pre.2.fix.1, il est pollué par la tentative abandonnée de migration Gradle 9. Il faut alors le régénérer intégralement avec la CLI Tauri officielle, sous JDK 17 :

rm -rf crates/apps/game-snake-poc-tauri/gen/android
(cd crates/apps/game-snake-poc-tauri && cargo tauri android init)

L'audit de distribution vérifie désormais un gen/android présent et refuse un wrapper/AGP qui ne correspondent pas au template Tauri 2.11.x attendu.

Smoke Android de développement

Lancer ensuite :

(cd crates/apps/game-snake-poc-tauri && cargo tauri android dev)

Choisir l'appareil réel ou l'AVD voulu lorsque la CLI le demande. Le frontend doit afficher le Canvas Snake, les compteurs score/longueur, les contrôles directionnels et les assets snake / engine-v1. La provenance doit évoluer depuis android / tauri-webview / wasm / <device> / unknown vers un profil d'entrée observé (touch, keyboard-mouse ou mixed) après utilisation des contrôles. Les événements de démarrage doivent apparaître dans le tracing/logcat.

Ne pas utiliser npm run dev ou npm run build comme gate manuelle : ces scripts sont des hooks internes possédés par Tauri. cargo tauri android build reste réservé au jalon de packaging prévu par le plan, sauf diagnostic explicite.

Appareil Android réel via USB

Sur un appareil physique, Tauri remplace automatiquement le host localhost du devUrl par une adresse réseau. Pour la gate de référence, le chemin reproductible retenu évite le LAN et utilise le tunnel USB ADB sur le même port HTTP/WebSocket Vite :

adb -s <serial> reverse --remove-all
adb -s <serial> reverse tcp:1436 tcp:1436
adb -s <serial> reverse --list

(cd crates/apps/game-snake-poc-tauri && cargo tauri android dev --host 127.0.0.1)

Le serial vient de adb devices -l et ne doit jamais être enregistré dans les sources. La configuration Vite utilise le port 1436 pour HTTP et WebSocket afin que le même tunnel transporte aussi le HMR. Un port HMR séparé n'appartient pas au contrat de ce POC.

Pour vérifier l'ABI réelle avant le smoke :

adb -s <serial> shell getprop ro.product.cpu.abi
adb -s <serial> shell getprop ro.product.cpu.abilist

arm64-v8a correspond à la cible Rust aarch64-linux-android, tandis que les AVD utilisés jusqu'ici sont x86_64-linux-android.

Positionnement

game-snake-poc-tauri est un POC de référence. Il ne doit pas être utilisé comme base automatique des futurs jeux Android ; la cible Android productive reste SDL3 natif tant qu’un besoin concret ne justifie pas la WebView Tauri.

Smoke lifecycle 0-pre.4

Pendant cargo tauri android dev :

1. lancer une partie et effectuer au moins une entrée tactile ;
2. mettre l’application en arrière-plan puis la ramener au premier plan ;
3. vérifier que le serpent reprend sans accélération ni rattrapage de la durée passée en background ;
4. faire pivoter/redimensionner l’émulateur si disponible et vérifier que le Canvas reste rendu ;
5. utiliser Back Android : pour Snake, l’application doit suivre le comportement système de sortie, sans navigation Web interne ni interception spécifique ;
6. vérifier dans logcat les traces runtime paused, runtime resumed et les événements visibility hidden/visible.

Le D-pad placé sous le Canvas est une limite ergonomique connue du POC de référence et n’est pas un critère bloquant de cette gate.

Sur le Galaxy S9+ ARM64 utilisé pour la validation réelle, chargement, WASM, Canvas, assets et touch fonctionnent via le tunnel USB. Un premier smoke a observé un abort natif FORTIFY: pthread_mutex_lock called on a destroyed mutex pendant Back/teardown ; après passage de HTTP et HMR sur le même tunnel 1436, le smoke 0-pre.4.fix.1 n'a pas reproduit l'abort et est allé jusqu'au détachement de la fenêtre. Le risque reste enregistré comme potentiellement intermittent et doit encore être retesté sur l'APK autonome beta ; il n'est pas contourné par une modification de gen/android.

Packaging beta Android

À partir de 0.3.1-2-beta.1, le packaging de validation utilise un APK Debug autonome contenant les deux ABI réellement testées par ce POC : arm64-v8a pour l'appareil physique et x86_64 pour l'AVD. Le build reste possédé par Tauri ; son hook beforeBuildCommand construit le WASM release, génère les bindings, exécute TypeScript/Vite et copie les assets.

export JAVA_HOME=/usr/lib/jvm/temurin-17-jdk-amd64
(cd crates/apps/game-snake-poc-tauri && \
  cargo tauri android build --debug --apk --target aarch64 --target x86_64)

Ne pas lancer npm run build séparément pour cette gate. Tauri affiche le chemin de l'APK produit ; les outputs sous gen/android/**/build/ sont générés et ignorés. Vérifier ensuite que l'APK contient les bibliothèques arm64-v8a et x86_64, puis installer ce même APK successivement sur l'AVD et l'appareil réel avec adb install -r.

Le package autonome ne doit dépendre ni de Vite, ni du port 1436, ni d'un tunnel ADB. Le smoke beta revalide Canvas, assets, WASM, touch, lifecycle et plusieurs sorties Back.