131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
<!-- file: docs/development/010-SNAKE_WEB_FRONTEND.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Frontend du POC Snake Web direct
|
|
|
|
## Rôle
|
|
|
|
`Web/game-snake-poc/` est le premier host navigateur direct du projet. Il reste un package frontend autonome, extérieur au workspace Cargo, et consomme les bindings générés de `game-snake-poc-wasm`.
|
|
|
|
La séparation est volontaire :
|
|
|
|
```text
|
|
game-snake-poc
|
|
↓
|
|
game-snake-poc-wasm
|
|
↓ wasm-bindgen
|
|
Web/game-snake-poc
|
|
↓
|
|
HTML + Sass/Bootstrap 5 + TypeScript + Canvas
|
|
```
|
|
|
|
Le frontend ne réimplémente aucune règle de Snake. Il traduit uniquement les entrées navigateur, cadence les appels à `tick()` et dessine la scène portable exposée par le bridge WASM.
|
|
|
|
## Baseline frontend KSP
|
|
|
|
Le shell reprend volontairement la structure frontend utilisée par les applications Desk KSP :
|
|
|
|
```text
|
|
Web/game-snake-poc/
|
|
├── frontend/
|
|
│ ├── main.html
|
|
│ ├── sass/
|
|
│ │ ├── _app.scss
|
|
│ │ ├── _bootswatch.scss
|
|
│ │ ├── _fontawesome.scss
|
|
│ │ ├── _variables.scss
|
|
│ │ └── main.scss
|
|
│ └── ts/
|
|
│ ├── game.ts
|
|
│ ├── input.ts
|
|
│ └── main.ts
|
|
├── package.json
|
|
├── tsconfig.json
|
|
└── vite.config.ts
|
|
```
|
|
|
|
Les dépendances npm utiles sont alignées sur cette baseline : Bootstrap 5, Font Awesome, `sass-embedded`, TypeScript, Vite et les types nécessaires. Les dépendances propres à Tauri, SimpleBar ou au tracing frontend KSP ne sont pas importées car elles n'ont aucun rôle dans ce host navigateur direct.
|
|
|
|
Le thème reprend la baseline Bootstrap/Bootswatch Pulse des apps Desk KSP, avec un header, un footer et une carte de contenu adaptés au jeu. Cette réutilisation reste une convention de présentation du POC ; elle ne crée aucune dépendance entre les dépôts KSP et games.sasedev.
|
|
|
|
## Shell HTML et présentation
|
|
|
|
Le document `frontend/main.html` fournit :
|
|
|
|
- un header de statut inspiré du template Desk KSP ;
|
|
- un Canvas carré responsive pour le rendu du jeu ;
|
|
- les indicateurs de score, longueur et état de chargement ;
|
|
- quatre boutons directionnels tactiles ;
|
|
- une zone d'erreur de démarrage ;
|
|
- un footer léger commun au shell.
|
|
|
|
Bootstrap 5 et Font Awesome sont installés comme dépendances npm et intégrés au build Vite/Sass. Aucun CDN n'est nécessaire au POC local.
|
|
|
|
Le Sass spécifique reste limité au shell, au Canvas et au pavé directionnel. Le gameplay ne dépend ni de Bootstrap, ni de Font Awesome, ni du DOM.
|
|
|
|
## Entrées
|
|
|
|
Le frontend accepte :
|
|
|
|
- les flèches du clavier ;
|
|
- `WASD` ;
|
|
- `ZQSD` ;
|
|
- les quatre boutons directionnels tactiles/pointer.
|
|
|
|
Une entrée appelle uniquement `left()`, `right()`, `up()` ou `down()` sur `SnakeWasmGame`. La simulation continue d'avancer exclusivement via `tick()`.
|
|
|
|
## Rendu Canvas
|
|
|
|
Le frontend lit la couleur de fond et les rectangles normalisés exposés par `game-snake-poc-wasm`. Les coordonnées sont multipliées par la taille physique courante du Canvas.
|
|
|
|
Le Canvas suit sa taille CSS et le `devicePixelRatio` du navigateur. Cette tranche couvre le resize visuel nécessaire au shell ; la gestion complète du lifecycle navigateur reste prévue par `0-pre.5`.
|
|
|
|
## Build
|
|
|
|
Depuis la racine du dépôt, construire d'abord l'adapter WASM et ses bindings :
|
|
|
|
```bash
|
|
cargo build -p game-snake-poc-wasm --target wasm32-unknown-unknown
|
|
wasm-bindgen ../builds/sasedev-games/target/wasm32-unknown-unknown/debug/game_snake_poc_wasm.wasm \
|
|
--target web \
|
|
--out-dir ../builds/sasedev-games/game-snake-poc-web/wasm \
|
|
--out-name game_snake_poc_wasm
|
|
```
|
|
|
|
Puis installer et construire le frontend :
|
|
|
|
```bash
|
|
cd Web/game-snake-poc
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
Vite place son cache et le `dist/` sous :
|
|
|
|
```text
|
|
../builds/sasedev-games/game-snake-poc-web/
|
|
```
|
|
|
|
Le dépôt ne reçoit donc ni bindings WASM générés, ni `dist/`, ni cache Vite.
|
|
|
|
## Smoke navigateur
|
|
|
|
Après génération du WASM :
|
|
|
|
```bash
|
|
cd Web/game-snake-poc
|
|
npm run dev
|
|
```
|
|
|
|
Ouvrir `http://127.0.0.1:1434/main.html` et vérifier :
|
|
|
|
1. le statut passe à `Prêt` sans erreur ;
|
|
2. Snake est visible dans le Canvas ;
|
|
3. les flèches clavier déplacent Snake ;
|
|
4. `WASD` et `ZQSD` produisent les mêmes directions ;
|
|
5. les quatre boutons tactiles/pointer fonctionnent ;
|
|
6. le shell KSP-derived et le Canvas restent utilisables sur une largeur mobile et Desktop ;
|
|
7. score et longueur restent visibles et évoluent avec l'état WASM.
|
|
|
|
Le lifecycle complet, les assets, le logging structuré et la provenance runtime appartiennent à `0-pre.5`.
|