62 lines
2.0 KiB
Markdown
62 lines
2.0 KiB
Markdown
<!-- file: docs/development/007-ANDROID_JNI_BRIDGE.md -->
|
|
<!-- version: 3 -->
|
|
|
|
# Bridge Java/JNI Android
|
|
|
|
## Objectif
|
|
|
|
Le bridge Java/JNI sert uniquement aux services réellement Android qui ne sont pas déjà fournis de manière portable par SDL3.
|
|
|
|
L'input tactile de base ne passe pas par JNI : SDL3 fournit directement les événements de doigt et le moteur les convertit en `PointerState`.
|
|
|
|
## Contrat V1
|
|
|
|
La baseline expose un unique appel Java vers Rust :
|
|
|
|
```text
|
|
NativeBridge.nativeContractVersion() -> 3
|
|
```
|
|
|
|
`SaseGameActivity` vérifie ce contrat après `SDLActivity.onCreate()`.
|
|
|
|
Cette vérification détecte au démarrage :
|
|
|
|
- bibliothèque Rust non chargée ;
|
|
- symbole JNI absent ;
|
|
- divergence de version de bridge.
|
|
|
|
## Extension future
|
|
|
|
Les futurs services pourront ajouter des opérations dédiées pour :
|
|
|
|
- haptique Android ;
|
|
- partage natif ;
|
|
- facturation ;
|
|
- publicité ;
|
|
- notifications ;
|
|
- autres services dépendants du framework Android.
|
|
|
|
Ils ne doivent pas servir à réimplémenter les entrées, fenêtres ou événements déjà couverts par SDL3.
|
|
|
|
## Sécurité Rust
|
|
|
|
L'export JNI utilise un symbole nommé explicitement et reçoit deux pointeurs opaques JNI qui ne sont pas déréférencés.
|
|
|
|
Aucun bloc `unsafe` ni fonction `unsafe` n'est autorisé.
|
|
|
|
Si un futur service nécessite de manipuler réellement `JNIEnv`, il devra faire l'objet d'une tranche distincte avec une politique FFI réévaluée plutôt que d'élargir implicitement l'exception actuelle.
|
|
|
|
## Back Android
|
|
|
|
Back n'est pas une commande JNI du jeu pour la launcher Activity racine.
|
|
|
|
Sur Android 16 / API 36+, `SaseGameActivity` enregistre uniquement un observer :
|
|
|
|
```text
|
|
OnBackInvokedDispatcher.PRIORITY_SYSTEM_NAVIGATION_OBSERVER
|
|
```
|
|
|
|
Cet observer écrit un événement logcat mais ne consomme pas la navigation. Android conserve donc son comportement système, notamment le Back-to-home et son animation prédictive.
|
|
|
|
Le moteur SDL conserve parallèlement la prise en charge de `AcBack` lorsqu'une plateforme SDL produit réellement cet événement.
|