194 lines
5.5 KiB
Markdown
194 lines
5.5 KiB
Markdown
<!-- file: docs/development/008-WASM_TAURI_POC.md -->
|
||
<!-- version: 5 -->
|
||
|
||
# POC WebAssembly embarqué dans Tauri
|
||
|
||
## Objectif
|
||
|
||
Le POC vérifie qu'une même crate de gameplay Rust peut fonctionner :
|
||
|
||
- dans le runner Desktop SDL3 natif ;
|
||
- compilée en WebAssembly ;
|
||
- dans une WebView Tauri locale ;
|
||
- sans site distant ni serveur applicatif.
|
||
|
||
Le POC ne remplace pas le runner SDL3 natif.
|
||
|
||
## Découpage
|
||
|
||
```text
|
||
game-reflex-poc
|
||
|
|
||
+--> game-reflex-poc-desktop --> engine-v1-sdl --> SDL3 natif
|
||
|
|
||
+--> game-reflex-poc-tauri --wasm32--> wasm-bindgen --> Canvas Web
|
||
|
|
||
+--natif--> Tauri WebView
|
||
```
|
||
|
||
Le JavaScript ne contient aucune règle Reflex. Il traduit les événements pointeur vers l'adaptateur WASM et dessine la scène générique exposée par le moteur.
|
||
|
||
## Frontend local
|
||
|
||
Tauri agit comme hôte de fichiers Web statiques locaux. `frontendDist` pointe sur :
|
||
|
||
```text
|
||
Tauri/game-reflex-poc/frontend/
|
||
```
|
||
|
||
Aucun site, CDN, Vite ou gestionnaire de paquets JavaScript n'est requis par ce POC.
|
||
|
||
## Sécurité
|
||
|
||
La CSP reste locale. `wasm-unsafe-eval` est autorisé uniquement parce que la WebView charge du WebAssembly.
|
||
|
||
Aucun script distant n'est autorisé.
|
||
|
||
## Build WASM
|
||
|
||
Préparer une fois :
|
||
|
||
```bash
|
||
rustup target add wasm32-unknown-unknown
|
||
cargo install wasm-bindgen-cli --locked
|
||
```
|
||
|
||
Puis :
|
||
|
||
```bash
|
||
python3 scripts/build_reflex_tauri_wasm.py
|
||
```
|
||
|
||
Les fichiers générés sont ignorés par Git.
|
||
|
||
## Prérequis Tauri Linux
|
||
|
||
Le développement Tauri v2 requiert les bibliothèques système WebKitGTK/GTK correspondantes.
|
||
|
||
Sur Debian, vérifier notamment la présence de `libwebkit2gtk-4.1-dev` et des autres prérequis documentés par Tauri avant la gate Tauri.
|
||
|
||
Installer une fois le CLI si nécessaire :
|
||
|
||
```bash
|
||
cargo install tauri-cli --version "^2.0.0" --locked
|
||
```
|
||
|
||
## Exécution
|
||
|
||
Après génération du WASM :
|
||
|
||
```bash
|
||
cd crates/apps/game-reflex-poc-tauri
|
||
cargo tauri dev
|
||
```
|
||
|
||
Critères :
|
||
|
||
- une fenêtre locale 405 × 720 s'ouvre ;
|
||
- le Canvas affiche le même fond et la même cible que Reflex SDL3 ;
|
||
- cliquer sur la cible incrémente le score et déplace la cible ;
|
||
- aucun site distant n'est requis ;
|
||
- le runtime est identifiable comme `Desktop + Wasm + TauriWebView + KeyboardMouse`.
|
||
|
||
## Frontière services Web
|
||
|
||
Ce POC ne choisit aucune régie publicitaire.
|
||
|
||
Il valide seulement qu'une variante Tauri possède une WebView capable d'héberger une frontière Web distincte. Ads, rewarded ads, revive, analytics et autres services resteront derrière `engine-v1-platform-api` et feront l'objet de tranches dédiées.
|
||
|
||
## Frontière de dépendances WASM
|
||
|
||
Les crates de gameplay `game-reflex-poc` et `game-snake-poc` ne dépendent pas de `engine-v1-sdl`.
|
||
|
||
Le backend SDL3 appartient aux runners natifs. Cette séparation est obligatoire pour que le graphe `wasm32-unknown-unknown` ne tire pas SDL3 ni ses dépendances natives.
|
||
|
||
## Icône de développement
|
||
|
||
Tauri attend une icône PNG lors de la génération du contexte natif. Le POC contient donc :
|
||
|
||
```text
|
||
crates/apps/game-reflex-poc-tauri/icons/icon.png
|
||
```
|
||
|
||
Il s'agit d'une icône minimale de développement ; l'identité graphique définitive viendra plus tard.
|
||
|
||
## Réorganisation fix.2
|
||
|
||
La crate Tauri et la crate WASM sont désormais séparées.
|
||
|
||
```text
|
||
crates/apps/game-reflex-poc-tauri/
|
||
├── src/lib.rs
|
||
├── src/tauri.rs
|
||
├── src/runtime.rs
|
||
├── src/main.rs
|
||
├── frontend/
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── vite.config.ts
|
||
└── tauri.conf.json
|
||
|
||
crates/apps/game-reflex-poc-wasm/
|
||
├── src/lib.rs
|
||
└── src/runtime.rs
|
||
```
|
||
|
||
`lib.rs` joue le rôle de façade. `tauri.rs` contient le pont Web/Rust et l'assemblage Tauri. Les fonctions métier/runtime sont portées par leurs modules puis appelées par les commandes Tauri.
|
||
|
||
Le frontend utilise Vite + TypeScript. Le build WASM reste séparé et produit les bindings `wasm-bindgen` dans `frontend/wasm/`.
|
||
|
||
Le logging est unifié avec `tracing` :
|
||
|
||
- `tracing` côté Rust ;
|
||
- `tauri-plugin-tracing` côté Tauri ;
|
||
- `@fltsci/tauri-plugin-tracing` côté TypeScript ;
|
||
- capability `tracing:default`.
|
||
|
||
Les événements frontend utiles sont donc remontés dans le même système de traces que le backend Rust.
|
||
|
||
## Logging fix.3
|
||
|
||
Le plugin Tauri ne remplace pas l'initialisation du subscriber `tracing`.
|
||
|
||
`game-logging-lib::init_console_tracing()` installe le subscriber console avant le premier événement Tauri.
|
||
|
||
Le frontend possède un wrapper TypeScript unique qui invoque `emit_frontend_log`; Rust valide le niveau et la cible puis réémet l'événement avec `tracing`.
|
||
|
||
`attachConsole()` reste activé pour rendre également les événements Rust observables dans la console WebView.
|
||
|
||
## Escape fix.3
|
||
|
||
`Escape` suit désormais le contrat moteur commun :
|
||
|
||
```text
|
||
keydown Escape
|
||
-> ReflexWasmGame::quit_requested_escape()
|
||
-> EngineGame::quit_requested(QuitSource::Escape)
|
||
-> QuitDecision
|
||
-> close_main_window uniquement si Exit
|
||
```
|
||
|
||
Une future politique de pause/confirmation pourra retourner `Continue` sans modifier le bridge Tauri.
|
||
|
||
## Répertoire de build externe
|
||
|
||
Comme Cargo via `.cargo/config.toml`, Tauri/Vite ne doivent créer aucun répertoire de build dans `sasedev-games`.
|
||
|
||
Depuis `crates/apps/game-reflex-poc-tauri`, le root de build Vite résout désormais :
|
||
|
||
```text
|
||
../../../../builds/sasedev-games/game-reflex-poc-tauri/
|
||
```
|
||
|
||
soit, depuis la racine du dépôt :
|
||
|
||
```text
|
||
../builds/sasedev-games/game-reflex-poc-tauri/
|
||
├── dist/
|
||
└── vite-cache/
|
||
```
|
||
|
||
`tauri.conf.json` référence le même `dist/` externe.
|
||
|
||
La racine du dépôt ne doit jamais contenir `builds/`.
|