games/prompts/004-V0_3_3_START_PROMPT.md

Prompt de démarrage 0.3.3 — Android SDL3 natif multi-ABI et packaging Gradle

1. Base exacte et version cible

Partir uniquement de la version stable/taggée :

v0.3.1

Si ce prompt est lu avant la publication effective de 0.3.1, ne pas ouvrir 0.3.3. Terminer d'abord la RC puis la release stable 0.3.1.

0.3.2 est volontairement différée : ne pas créer de placeholder, de version vide ou de POC Tauri Desktop par cérémonial. Sa réouverture dépend d'un bénéfice produit concret, notamment une monétisation Desktop/WebView réellement démontrée.

Version cible active :

0.3.3

Première tranche obligatoire :

0.3.3-0-pre.1

0-pre.1 est le gate de cadrage : audit, requirements, recherche ciblée, sizing, risques, matrice de validation et création du plan actif sous docs/plans/. Ne pas commencer directement par une réécriture Gradle.

2. Sources de vérité

Lire intégralement, dans cet ordre :

RULES.md
ROADMAP.md
CHANGELOG.md
docs/000-README.md

Puis au minimum :

docs/rules/RULES_GENERAL.md
docs/rules/RULES_RUST.md
docs/rules/RULES_PROJECT.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/RULES_COMMANDS.md
docs/rules/RULES_VALIDATION_MATRIX.md
docs/rules/RULES_SESSION_PLANNING.md
docs/rules/PROMPT_STRUCTURE.md

Transmission plateforme/Android :

docs/plans/002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md
docs/architecture/002-ANDROID_ARCHITECTURE.md
docs/architecture/003-SDL3_PLATFORM_ABSTRACTION.md
docs/architecture/004-INPUT_AND_CONTROLS.md
docs/architecture/005-ASSET_ARCHITECTURE.md
docs/architecture/010-RUNTIME_PROVENANCE.md
docs/architecture/015-PLATFORM_POC_ARCHITECTURE.md
docs/development/006-ANDROID_RUST_NATIVE_BUILD.md
docs/development/007-ANDROID_JNI_BRIDGE.md
docs/testing/005-V0_3_1_RC_VALIDATION_MATRIX.md
history/0.3.1/
deltas/0.3.1/

Auditer ensuite le code réellement concerné :

Android/
crates/apps/game-android-entrypoint/
crates/engines/engine-v1-sdl/
crates/engines/engine-v1-platform-api/
crates/games/game-reflex-poc/
crates/games/game-snake-poc/
assets/
scripts/build_android_rust.py

Le script Python historique est une source d'information sur le pipeline existant, pas la cible d'orchestration à conserver.

3. État hérité attendu

La stable 0.3.1 doit laisser :

• Desktop SDL3 natif fonctionnel ;
• Android SDL3/Java/JNI historique déjà capable d'exécuter Reflex et Snake ;
• game-android-entrypoint comme cdylib commun sélectionnant exactement un jeu ;
• SDL3 AAR/Prefab et cargo-ndk déjà connus du dépôt ;
• Tauri Android Snake conservé uniquement comme POC de référence ;
• preuve qu'un même package Android peut couvrir ARM64 réel et x86_64 émulateur ;
• décision produit : la voie Android de production est SDL3 native.

Ne pas réutiliser Tauri, WebView ou WASM dans le packaging Android natif uniquement parce qu'ils existent dans 0.3.1.

4. Mission 0.3.3

Transformer le chemin Android SDL3 natif historique en pipeline multi-ABI reproductible possédé par Cargo/Gradle, sans script Python de build, et préparer une distribution Android réellement adaptée aux futurs jeux.

Le résultat attendu doit permettre au minimum :

Gradle -> build Rust natif -> SDL3/JNI -> APK de test
Gradle -> plusieurs ABI -> APK universal de test
Gradle -> plusieurs ABI pertinentes -> AAB de distribution

Le choix final des ABI et du minSdk doit être fondé sur les contraintes réellement vérifiées de SDL3, NDK, AGP, Rust et du code projet.

5. Multi-ABI et anciennes versions Android : deux sujets distincts

Ne pas confondre :

• ABI CPU : arm64-v8a, x86_64, éventuellement armeabi-v7a si elle reste techniquement et produitement justifiée ;
• version Android / API level : minSdk, targetSdk, compileSdk.

arm64-v8a est la cible appareil productive minimale actuelle ; x86_64 reste utile pour les AVD. Le support armeabi-v7a n'est pas automatiquement requis pour supporter un Android ancien : il doit être évalué séparément.

Le souhait produit est de supporter des versions Android anciennes lorsque cela reste raisonnable. 0-pre.1 doit donc vérifier la documentation officielle actuelle et le pipeline réel avant de fixer un minSdk; ne pas recopier aveuglément une valeur historique du dépôt.

6. Packaging attendu

Pour les tests locaux, viser un APK universal multi-ABI afin qu'un seul artefact puisse être installé sur les appareils/AVD couverts.

Pour la distribution future, privilégier un Android App Bundle :

app-release.aab

contenant les ABI réellement retenues. La signature/keystore de publication reste hors dépôt et ne doit jamais être inventée ou embarquée dans les sources.

La version doit documenter clairement la différence entre :

APK universal -> sideload/tests
AAB           -> distribution store
APK split ABI -> option technique, pas artefact par défaut sans besoin

7. Architecture et ownership

Conserver les décisions suivantes :

• Rust porte gameplay et moteur ;
• SDL3 porte la couche plateforme graphique/input native ;
• Java reste la glue Android préférée ; Kotlin n'est pas introduit sans besoin démontré ;
• le contrat JNI reste petit ;
• Android/common porte le commun durable ;
• chaque Android/game-* reste une application distincte ;
• assets communs et spécifiques restent canoniques sous assets/ et sont packagés sans duplication source ;
• les bibliothèques jniLibs générées ne sont pas versionnées ;
• aucun build Android productif ne dépend de Tauri.

8. Orchestration de build

La cible 0.3.3 est de supprimer le besoin de scripts/build_android_rust.py dans le chemin normal de build Android.

Le cadrage doit comparer les options propres disponibles dans Gradle/NDK/Cargo, par exemple l'invocation contrôlée de cargo ndk depuis des tâches Gradle, sans créer un nouveau script ad hoc dans un autre langage uniquement pour déplacer le problème.

Le résultat doit garantir :

• choix explicite des ABI ;
• build Rust avec exactement une feature jeu ;
• mise à disposition de libgame_android_entrypoint.so et libSDL3.so par ABI ;
• dépendances de tâches Gradle correctes ;
• rebuild incrémental raisonnable ;
• erreurs visibles et déterministes ;
• outputs générés hors sources versionnées.

9. Scope inclus

À cadrer puis implémenter progressivement :

• pipeline Gradle/Cargo natif multi-ABI ;
• au minimum Snake comme jeu-sonde, puis Reflex si la factorisation commune le rend naturel dans la même version ;
• APK universal de test ;
• AAB de validation de distribution sans secrets ;
• choix documenté des ABI ;
• étude et validation du minSdk soutenable ;
• smoke x86_64 AVD et ARM64 réel ;
• si un AVD d'API plus ancienne compatible est disponible ou raisonnablement créable, smoke ciblé du plancher Android retenu ;
• mise à jour des docs Android/Gradle/JNI/validation ;
• suppression du script Python du chemin de build normal, puis suppression du fichier lui-même seulement si aucune autre responsabilité durable ne le justifie.

10. Hors scope

Ne pas intégrer dans 0.3.3 sans découverte bloquante :

• Tauri Desktop ;
• nouvelles fonctionnalités de gameplay ;
• réseau realtime ;
• publicité AdMob effective ;
• billing ;
• authentification ;
• Uroburas ;
• iOS ;
• migration vers Kotlin ;
• moteur V2 ;
• optimisation prématurée par ABI sans mesure.

L'AAB est un objectif de packaging, pas une ouverture du scope monétisation/store complet.

11. 0-pre.1 obligatoire

Avant tout développement lourd :

1. auditer les modules Gradle existants et leurs versions ;
2. auditer scripts/build_android_rust.py et distinguer ce qu'il orchestre réellement ;
3. vérifier la version SDL3/AAR réellement utilisée et sa documentation Android actuelle ;
4. vérifier AGP/Gradle/JDK/NDK et les API Android requises ;
5. inventorier les ABI installables/testables localement ;
6. distinguer support OS ancien et support CPU 32 bits ;
7. proposer le minSdk candidat avec justification et stratégie de test ;
8. définir APK universal, AAB et éventuels splits ;
9. définir les gates par jalon ;
10. créer docs/plans/003-V0_3_3_ANDROID_NATIVE_MULTI_ABI_PLAN.md avec un forecast souple jusqu'à stable.

Si le scope ne tient pas raisonnablement dans une session/version, le découper dès 0-pre.1 plutôt que d'allonger artificiellement les prereleases.

12. Validation et responsabilité

Les audits statiques peuvent être exécutés par le générateur. Les builds Cargo/Gradle, tests et smokes finaux restent côté utilisateur conformément aux règles du dépôt et ne sont jamais déclarés réussis sans sortie réelle.

Dès qu'un fichier Rust/Cargo change, appliquer la gate Rust normale. Dès qu'Android/Gradle change, ajouter les tâches Gradle ciblées prévues par le plan. Les tests workspace complets restent réservés aux jalons larges/finalisation selon la matrice.

Les commandes nécessitant un changement de répertoire utilisent un sous-shell :

(cd Android && <commande>)

13. Documentation, deltas et historique

Chaque tranche produit deltas/0.3.3/<jalon>.md avec base, scope, fichiers et validations attendues.

history/0.3.3/<jalon>.md n'est créé que par la tranche suivante après validation effective du jalon précédent.

CHANGELOG.md reste normalement silencieux pendant pre/alpha/beta et est consolidé à partir de la première RC. ROADMAP.md reste macroscopique.

Les nouvelles responsabilités Android durables doivent être documentées au moment où elles deviennent réelles, pas repoussées intégralement à la fin.

14. Forecast initial non contraignant

Le 0-pre.1 doit réviser ce forecast à partir de l'audit :

0-pre.1   audit + requirements + choix ABI/API + plan
0-pre.2   orchestration Gradle/Cargo native sur une ABI
0-pre.3   multi-ABI + APK universal
0-pre.4   AAB + compatibilité Android/minSdk + smokes
2-beta.1  validation large et packaging final
3-rc.1    gel et reproductibilité
0.3.3     promotion mécanique stable

Les numéros peuvent être regroupés/scindés selon les résultats réels. Une version doit néanmoins être menée jusqu'à stable dans la session autant que possible.

15. Première gate de reprise

Après lecture/audit et avant la livraison 0-pre.1, relever au minimum :

rustc --version
cargo --version
rustup target list --installed
java -version
printf 'JAVA_HOME=%s\nANDROID_HOME=%s\n' "$JAVA_HOME" "$ANDROID_HOME"
adb version
adb devices -l
emulator -list-avds
(cd Android && gradle --version)

Compléter par les versions/chemins NDK, SDK, AGP, SDL3 AAR et cargo ndk réellement trouvés dans la baseline.

16. Critère de réussite

0.3.3 réussit lorsque le build Android SDL3 natif n'a plus besoin d'un orchestrateur Python, qu'un artefact de test multi-ABI reproductible est produit, qu'un AAB de distribution peut être construit sans secrets embarqués, que le support Android/ABI est explicitement documenté et testé selon les moyens disponibles, et que Snake reste fonctionnel sans régression du moteur partagé.