Sasedev/games
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.3.0-0-pre.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-20 06:15:50 +02:00
parent 74be610697
commit 54079accb5
9 changed files with 567 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/studies/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/studies/000-README.md -->
<!-- version: 8 -->
<!-- version: 9 -->
# Études
@@ -53,3 +53,7 @@ Ces documents étudient les POC à réaliser ; ils ne lancent encore aucune impl
- [`020-UROBURAS_CRATE_DECOMPOSITION_STUDY.md`](020-UROBURAS_CRATE_DECOMPOSITION_STUDY.md) — proposition de familles de crates et dépendances sans monolithe jeu.
- [`021-UROBURAS_SERVER_REFERENCE_STACK.md`](021-UROBURAS_SERVER_REFERENCE_STACK.md) — stack serveur de référence Actix/Tokio/tokio-tungstenite/Maud/Fluent/Lettre et gRPC/Tonic conditionnel.
- [`022-UROBURAS_IMPLEMENTATION_DEPENDENCY_ORDER.md`](022-UROBURAS_IMPLEMENTATION_DEPENDENCY_ORDER.md) — ordre d'implémentation recommandé pour le Mode 1 avant les modes multijoueurs.
## Étude de cadrage 0.3.0
- [`023-V0_3_0_PLATFORM_POC_AUDIT.md`](023-V0_3_0_PLATFORM_POC_AUDIT.md) — audit réel de la baseline `0.2.0`, requirements Snake, graphe de dépendances, choix du premier POC et sizing corrigé de `0.3.0`.

354
docs/studies/023-V0_3_0_PLATFORM_POC_AUDIT.md Normal file
View File

@@ -0,0 +1,354 @@
<!-- file: docs/studies/023-V0_3_0_PLATFORM_POC_AUDIT.md -->
<!-- version: 1 -->
# 0.3.0 — audit de baseline et cadrage du premier POC plateforme
## Statut
Étude de cadrage pour `0.3.0-0-pre.1`.
Elle décrit l'état observé de la stable `0.2.0`, les requirements réellement nécessaires à Snake, le premier POC retenu et le sizing corrigé. Elle ne transforme pas encore les extractions candidates en architecture durable.
## Base inspectée
Base déclarée : tag stable `v0.2.0`, fourni sous forme d'archive `games-v0.2.0.zip`.
L'intégrité ZIP est propre. L'archive ne contient pas `.git` : l'état du commit, le tag effectif et la propreté du working tree ne peuvent donc pas être vérifiés dans cet environnement.
La version workspace observée avant modification est `0.2.0`.
## Audits officiels exécutés sur la baseline
Les audits en lecture seule suivants passent sur la baseline telle que livrée :
```text
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
games.sasedev workspace audit: clean
Markdown table audit: clean (4 table(s), 158 file(s))
Distribution layout audit: clean (19 required path(s), 1 forbidden path(s) absent)
```
Ces résultats valident uniquement les contrôles mécaniques réellement couverts par les scripts. La revue manuelle des règles a détecté des écarts supplémentaires.
## Écarts de baseline détectés
### README de version obsolète
`README.md` annonce encore `0.1.0` comme stable et `0.2.0` comme candidate alors que l'archive est la stable `0.2.0`.
Correction dans `0-pre.1` : afficher `0.2.0` comme stable de référence et `0.3.0-0-pre.1` comme version de développement.
### ROADMAP stable non fermé
`ROADMAP.md` conserve quatre lignes `( )` sous `0.2.0`. Cela contredit `DOC-RMAP-010`, qui interdit du scope encore planifié sous une version stable clôturée.
La revue du contenu `0.2.0` montre que :
- layering et dépendances ont été couverts par les études puis l'architecture consolidée ;
- matrice plateforme et pressure tests ont été produits ;
- la composition Rust statique a été retenue ;
- le manifest produit/jeu et l'architecture physique définitive des crates ne sont volontairement pas figés ;
- la trajectoire `0.3.x` puis `0.4.x` a été définie.
Correction dans `0-pre.1` : fermer les lignes réellement livrées et marquer explicitement le manifest/shape physique définitif comme reporté.
### Effet de bord de la gate d'audit Python
Le ZIP `v0.2.0` ne contient aucun `__pycache__` ni fichier `.pyc`. En revanche, l'exécution de `scripts/audit_rust_workspace_rules.py` sur la baseline crée `scripts/__pycache__/audit_rust_general_rules.cpython-313.pyc` : `audit_rust_export_completeness.py` importe `audit_rust_general_rules.py` dans un sous-processus Python standard.
Cela contredit l'intention de `CMD-GEN-006`, selon laquelle les audits sont des contrôles en lecture seule. Correction dans `0-pre.1` : le wrapper exécute désormais ses trois sous-audits avec l'interpréteur courant et `-B`, ce qui supprime cet effet de bord sans modifier les audits eux-mêmes. Une réexécution complète confirme qu'aucun cache Python n'est créé.
### Règle RC encore spécifique à 0.1.0
`CMD-RC-001` parle encore du gel fonctionnel de `0.1.0`. La règle est générale et doit viser la version courante.
Correction dans `0-pre.1` : formulation générique.
### Build Python historique et cohérence normative
La revue des règles révèle une contradiction dans `0.2.0` : `CMD-BUILD-002` interdisait globalement qu’un script Python pilote un build, tandis que `CMD-BUILD-004` demandait précisément aux POC `0.3.x` de remplacer les orchestrateurs Python encore présents. La baseline conserve effectivement deux chemins historiques qui les utilisent.
Deux scripts historiques pilotent encore des builds :
- `scripts/build_reflex_tauri_wasm.py` ;
- `scripts/build_android_rust.py`.
Le premier est encore appelé par les hooks Tauri Reflex. Le second orchestre `cargo ndk`, l'extraction SDL3 depuis l'AAR et le staging `jniLibs`.
Ils appartiennent à la baseline validée `0.1.0`, mais un POC `0.3.x` ne doit pas les reprendre comme mécanisme de build. `CMD-BUILD-002` est rendue cohérente avec cette migration : les deux orchestrateurs sont explicitement tolérés uniquement comme baseline gelée jusqu’à la réactivation du chemin concerné. `CMD-WEB-003` qualifie également le script Tauri/WASM comme historique. Les remplacements sont réalisés lorsque le chemin concerné devient actif : Web direct en `0.3.0`, Tauri Android/Desktop dans les versions correspondantes et Android natif multi-ABI dans sa tranche dédiée.
## Contraintes de l'environnement courant
L'environnement d'inspection dispose de :
```text
Python 3.13.5
Node.js v22.16.0
npm 10.9.2
OpenJDK 21
```
Il ne dispose pas de :
```text
cargo
rustc
rustup
gradle
wasm-bindgen
cargo-ndk
Tauri CLI
```
L'archive ne contient pas de Gradle Wrapper et ne vend pas l'AAR SDL3, conformément à la baseline Android actuelle.
Conséquence : seuls les audits statiques et inspections de fichiers sont exécutables ici. Les builds, tests et smokes restent à exécuter par l'utilisateur conformément à `CMD-BUILD-005`.
## Inventaire Snake et hosts existants
### Gameplay Snake
`game-snake-poc` possède déjà :
- un état déterministe indépendant de SDL, Android, Tauri et Web ;
- des directions sémantiques `Left/Right/Up/Down` via `InputState` ;
- une cadence de déplacement interne ;
- collision mur/corps ;
- score et nourriture ;
- rendu sous forme de `EngineScene` normalisée.
Le jeu ne consomme aucun symbole de `engine-v1-platform-api`, bien que cette dépendance soit encore déclarée dans son manifest. La même déclaration inutilisée existe dans `game-reflex-poc`. Cette dette est à nettoyer avant le premier adapter Web.
### Desktop SDL3
`engine-v1-sdl` fournit déjà :
- fenêtre redimensionnable ;
- clavier directionnel ;
- pointeur normalisé ;
- swipe tactile/souris ;
- quit par fermeture, Escape et Back plateforme ;
- rendu de rectangles normalisés ;
- boucle fixed-step de 16 ms utilisée par les runners.
Le runner Snake Desktop compose correctement gameplay, SDL, logging et capacité plateforme désactivée. Il reste la baseline de non-régression pour `0.3.0`.
### Android SDL3 / Java / JNI
La baseline possède :
- `SaseGameActivity` commune dérivée de `SDLActivity` ;
- un bridge JNI versionné ;
- un `cdylib` Rust commun sélectionnant Reflex ou Snake par feature ;
- tactile transporté par SDL3 ;
- observation Back Android 16 non consommatrice ;
- staging Gradle des assets ;
- configuration NDK centralisée.
Le chemin build Rust Android reste toutefois orchestré par Python et n'est pas réutilisé par le premier POC `0.3.0`.
### Référence Tauri/WASM Reflex
La référence Reflex valide déjà plusieurs conventions utiles :
- crate WASM distincte de la crate Tauri ;
- `lib.rs` Tauri limité à la façade/réexport ;
- `tauri.rs` propriétaire de l'assemblage et des commandes ;
- frontend Vite/TypeScript dans la crate Tauri ;
- tracing frontend relayé vers Rust ;
- canvas redimensionné selon le viewport et le device pixel ratio.
Les APIs WASM et le frontend restent cependant Reflex-specific. Elles sont des références à adapter, pas du code générique à copier aveuglément.
## Graphe de dépendances local observé
```text
engine-v1-common
engine-v1-platform-api
engine-v1-sdl
-> engine-v1-common
game-snake-poc
-> engine-v1-common
-> engine-v1-platform-api [déclarée, non utilisée]
game-reflex-poc
-> engine-v1-common
-> engine-v1-platform-api [déclarée, non utilisée]
game-snake-poc-desktop
-> game-snake-poc
-> engine-v1-common
-> engine-v1-platform-api
-> engine-v1-sdl
-> game-logging-lib
game-android-entrypoint
-> engine-v1-common
-> engine-v1-sdl
-> game-logging-lib
-> game-snake-poc / game-reflex-poc via features
game-reflex-poc-wasm
-> engine-v1-common
-> game-reflex-poc
game-reflex-poc-tauri Rust
-> engine-v1-platform-api
-> game-logging-lib
frontend Reflex Tauri
-> bindings générés game-reflex-poc-wasm
game-assets-lib
-> aucun consommateur runtime actuel
```
Le graphe confirme que gameplay Snake et host peuvent être séparés sans créer un nouveau moteur.
## Requirements du premier POC Snake
| Besoin | Baseline réelle | Décision 0.3.0 |
|--------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Input clavier | SDL oui ; Web Snake absent | adapter clavier Web vers `GameAction` |
| Boutons directionnels tactiles | absent | quatre contrôles virtuels Web vers `GameAction` |
| Viewport / resize | SDL oui ; Reflex Web oui | réutiliser le principe canvas responsive sans coupler Snake à Tauri |
| Lifecycle | quit minimal ; pas de lifecycle Web générique | pause des ticks sur `visibilitychange`, reprise contrôlée, sortie/navigation host-specific |
| Runtime provenance | type présent mais non consommé | instancier une provenance Browser/WASM et refléter le profil d'input réellement utilisé |
| Assets | sources + resolver/staging présents ; aucun runtime ne charge actuellement les JSON | valider le packaging/chargement de `common` et `game` dans le POC Web |
| Logging | tracing natif ; bridge Tauri Reflex | logging Web local distinct de Tauri, sans dupliquer la logique gameplay |
| WASM bridge | Reflex-specific | créer un adapter Snake dédié ; n'extraire un bridge générique qu'après duplication réellement observée |
| Tauri bridge | Reflex Desktop uniquement | hors scope `0.3.0` |
| Android packaging | SDL/Java/JNI existant | hors scope `0.3.0` |
| Multi-ABI | script historique supportant plusieurs ABI | hors scope `0.3.0`, remplacement natif prévu plus tard |
## Duplications et extractions candidates
Duplications déjà visibles :
- runners Desktop Reflex/Snake très proches ;
- activities Android spécifiques volontairement minimales ;
- future exposition de `EngineScene` en WASM susceptible de répéter l'adapter Reflex ;
- shell frontend Canvas/input susceptible d'être commun au Web direct et à Tauri.
Décision : ne pas extraire un runner générique, un bridge WASM générique ou un shell Web commun dans `pre.1`. Le premier second consommateur réel décide de l'extraction.
## Choix du premier POC
Le premier POC de `0.3.0` est :
```text
Web navigateur direct + Snake
```
Le choix initial Tauri Android est reporté au second host, actuellement `0.3.1`.
Raisons :
- le Web direct exerce déjà WASM, keyboard/touch, resize, lifecycle, assets et provenance ;
- la référence Reflex fournit un précédent WASM/Canvas sans imposer Tauri ;
- Tauri Android ajouterait simultanément un nouveau gameplay WASM, un nouveau host mobile Tauri, le lifecycle mobile, le packaging Android Tauri et les plugins ;
- la baseline Web obtenue devient ensuite un point de comparaison et de réutilisation pour Tauri Android ;
- ce découpage réduit le risque de créer trop tôt une abstraction Tauri/Web commune sur la seule base de Reflex.
## Scope corrigé de 0.3.0
Inclus :
- correction des écarts de baseline détectés en `pre.1` ;
- nettoyage host-neutral de Snake ;
- maintien du runner Desktop SDL3 ;
- adapter WASM Snake dédié ;
- frontend Web direct Vite/TypeScript minimal ;
- clavier + boutons directionnels tactiles ;
- canvas responsive ;
- lifecycle navigateur minimal ;
- logging Web ;
- chargement d'assets de preuve ;
- provenance Browser/WASM ;
- build Web avec outils natifs ;
- audit de duplication et décisions d'extraction après POC.
Exclus :
- Tauri Android ;
- Tauri Desktop Snake ;
- remplacement du build Android natif multi-ABI ;
- publicité, billing, auth ou leaderboard ;
- réseau realtime ;
- WebTransport/QUIC ;
- logique Uroburas ;
- ECS, physique ou nouveau moteur.
## Sizing corrigé
Le forecast initial est réduit et réordonné afin que `0.3.0` reste une version de session unique.
### `0-pre.1` — audit, règles, requirements et sizing
- audit complet de la baseline ;
- correction des incohérences documentaires/règles détectées ;
- choix Web direct ;
- forecast corrigé ;
- aucune implémentation gameplay/host lourde.
### `0-pre.2` — Snake portability baseline
- supprimer les dépendances de plateforme inutiles des crates jeu concernées ;
- confirmer les actions sémantiques nécessaires à Snake ;
- conserver Desktop SDL3 comme non-régression ;
- préciser le contrat minimal attendu par l'adapter WASM.
### `0-pre.3` — adapter Snake WASM + build natif Web
- crate WASM Snake dédiée ;
- exposition input/update/scene strictement nécessaire ;
- procédure Cargo + `wasm-bindgen` reproductible sans Python ;
- tests ciblés de l'adapter lorsqu'ils sont possibles hors navigateur.
### `0-pre.4` — POC navigateur direct de bout en bout
- frontend Vite/TypeScript ;
- rendu Canvas ;
- clavier ;
- boutons tactiles ;
- resize ;
- visibility lifecycle ;
- logging ;
- assets ;
- provenance ;
- build et smoke navigateur réels côté utilisateur.
### `0-pre.5` — uniquement si le POC révèle un défaut réel
Cette tranche n'est pas créée artificiellement. Elle corrige une frontière, une duplication ou un bug observé.
### `2-beta.1` — validation large du scope retenu
Alpha n'est pas planifiée par défaut. Si `pre.4` est fonctionnellement complet, la beta valide le workspace affecté, le build Web de production et le smoke du POC.
### `3-rc.1` — candidate gelée
Documentation durable, commandes reproductibles, décisions d'extraction/report, ROADMAP et préparation de la version suivante. Aucun nouveau scope.
### `0.3.0` — promotion mécanique
Aucune nouvelle fonctionnalité.
## Critères de sortie de 0.3.0
`0.3.0` peut être clôturée lorsque :
- Snake Desktop SDL3 reste fonctionnel ;
- Snake fonctionne réellement dans un navigateur direct ;
- clavier et boutons tactiles produisent les mêmes actions sémantiques ;
- resize et visibility lifecycle ont été exercés ;
- assets et provenance sont observables ;
- le chemin Web ne dépend d'aucun script Python de build ;
- les duplications avec Reflex/Tauri sont documentées ;
- seules les abstractions prouvées nécessaires ont été extraites ;
- les validations applicables ont été exécutées par l'utilisateur ;
- aucune logique Uroburas ni réseau realtime n'a été introduite.