games/docs/development/008-WASM_TAURI_POC.md

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

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 :

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 :

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --locked

Puis :

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 :

cargo install tauri-cli --version "^2.0.0" --locked

Exécution

Après génération du WASM :

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 :

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.

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 :

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 :

../../../../builds/sasedev-games/game-reflex-poc-tauri/

soit, depuis la racine du dépôt :

../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/.