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

0.2.0-0-pre.1-fix.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-18 00:58:14 +02:00
parent de63a8c57b
commit df4a06fac3
23 changed files with 317 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/000-README.md
View File

@@ -9,8 +9,8 @@
## Idées et études
- [`ideas/README.md`](ideas/README.md) — rôle des idées non engagées et règles de maturation.
- [`studies/README.md`](studies/README.md) — rôle des études comparatives non normatives.
- [`ideas/000-README.md`](ideas/000-README.md) — rôle des idées non engagées et règles de maturation.
- [`studies/000-README.md`](studies/000-README.md) — rôle des études comparatives non normatives.
## Architecture
@@ -45,7 +45,7 @@
## Règles
Voir [`../RULES.md`](../RULES.md), notamment [`rules/RULES_DOCUMENTATION.md`](rules/RULES_DOCUMENTATION.md) pour la gouvernance documentaire et [`rules/RULES_COMMANDS.md`](rules/RULES_COMMANDS.md) pour la politique d'exécution des commandes.
Voir [`../RULES.md`](../RULES.md), notamment [`rules/RULES_DOCUMENTATION.md`](rules/RULES_DOCUMENTATION.md) pour la gouvernance documentaire, [`rules/RULES_COMMANDS.md`](rules/RULES_COMMANDS.md) pour la politique d'exécution et [`rules/RULES_VALIDATION_MATRIX.md`](rules/RULES_VALIDATION_MATRIX.md) pour la matrice des gates.
## Validation
@@ -65,4 +65,4 @@ Voir [`../RULES.md`](../RULES.md), notamment [`rules/RULES_DOCUMENTATION.md`](ru
## Historique validé
- [`../history/README.md`](../history/README.md) — convention et navigation de l'historique transitoire immuable des jalons validés.
- [`../history/000-README.md`](../history/000-README.md) — convention et navigation de l'historique transitoire immuable des jalons validés.

19
docs/architecture/003-SDL3_PLATFORM_ABSTRACTION.md
View File

@@ -15,17 +15,26 @@ Engine API
SDL3 boundary
┌───┼───────────────┐
│ │ │
Desktop Android Web
native SDL/JNI WASM/browser
Desktop Mobile Web
SDL native SDL/native WASM/browser
│ │
Linux/Windows/ Android/iOS
macOS
```
## Desktop
La famille Desktop réserve Linux, Windows et macOS. Leur support effectif dépend des backends, bibliothèques et contraintes de distribution disponibles au moment de l'implémentation.
Le runner Desktop est la cible d'itération la plus rapide. Il utilise la crate lib du jeu et, à terme, le runtime SDL3 natif. Les entrées disponibles peuvent inclure clavier, souris, trackpad, gamepad et joystick.
La cible Desktop sert à tester le gameplay, le rendu, la boucle de jeu, l'audio et les abstractions communes sans imposer un déploiement sur émulateur ou téléphone.
## Android
## Mobile
La famille Mobile réserve Android et iOS. Téléphone et tablette sont des classes de device et ne doivent pas être confondus avec l'OS ou le backend de rendu.
### Android
Android empaquette le jeu natif dans une application standard. La structure cible combine : SDL3 Android, une bibliothèque native Rust, la couche Java commune, les extensions Java spécifiques au jeu, les assets communs et spécifiques, puis les SDK Android requis.
@@ -33,6 +42,10 @@ Les fonctionnalités suivantes restent côté plateforme Android : lifecycle, JN
Le gameplay Rust ne doit pas dépendre des classes Java ni d'une régie publicitaire particulière.
### iOS
iOS est une cible réservée pour une évolution future. Aucun support de distribution iOS n'est exigé dans le POC actuel. L'architecture ne doit toutefois pas introduire une dépendance structurelle qui rendrait impossible un backend SDL/native ou un adapter iOS ultérieur.
## Web / WASM
La cible Web est prévue comme cible ultérieure. SDL3 peut être utilisé avec une chaîne Web adaptée, notamment Emscripten, tandis que le navigateur fournit ses propres contraintes de boucle d'événements, audio, stockage, permissions et interaction utilisateur.

2
docs/ideas/README.md → docs/ideas/000-README.md
View File

@@ -1,4 +1,4 @@
<!-- file: docs/ideas/README.md -->
<!-- file: docs/ideas/000-README.md -->
<!-- version: 1 -->
# Idées

11
docs/rules/FILE_CONTRACTS.md
View File

@@ -9,8 +9,8 @@
- `CHANGELOG.md` conserve une synthèse inversement chronologique à partir des jalons RC et stables.
- `docs/000-README.md` indexe la documentation détaillée.
- `docs/rules/` contient les règles durables.
- `docs/ideas/` contient des idées et variantes non engagées.
- `docs/studies/` contient des analyses comparatives non normatives préparant une décision.
- `docs/ideas/000-README.md` est le point d'entrée des idées et variantes non engagées.
- `docs/studies/000-README.md` est le point d'entrée des analyses comparatives non normatives préparant une décision.
- `docs/architecture/` contient les décisions et descriptions d'architecture retenues.
- `docs/objectives/` décrit les objectifs et la stratégie produit/technique.
- `docs/games/` classe les familles de jeux, leurs contrôles et leurs évolutions.
@@ -34,3 +34,10 @@
- `crates/apps/<game>-tauri/src/tauri.rs` assemble Tauri et porte le pont Web/Rust.
- `crates/apps/<game>-wasm/` contient l'adaptation WebAssembly distincte.
- Les bindings JavaScript et modules `.wasm` générés restent ignorés par Git.
## Points d'entrée documentaires
- Le `README.md` racine du dépôt conserve son nom.
- Un README propre à une crate, un package ou un répertoire technique peut conserver `README.md` lorsque cet usage est naturel à son écosystème.
- Un répertoire documentaire conçu pour accumuler plusieurs fichiers Markdown utilise `000-README.md` comme point d'entrée.
- `history/000-README.md` est le point d'entrée de l'historique validé.

17
docs/rules/RULES_COMMANDS.md
View File

@@ -29,8 +29,11 @@
- **CMD-RUST-008** — `cargo build` est utilisé lorsqu'un artefact exécutable ou une bibliothèque est réellement nécessaire ; il n'est pas lancé systématiquement en plus de `cargo check`.
- **CMD-RUST-009** — `cargo tree` et ses variantes sont des commandes de diagnostic de dépendances, pas des gates obligatoires de chaque delta.
- **CMD-RUST-010** — `cargo update` n'est jamais exécuté opportunistement. Toute mise à jour de dépendance doit appartenir à une tranche explicitement consacrée aux dépendances ou être nécessaire à la fonctionnalité en cours.
- **CMD-RUST-011** — `cargo clean` n'est pas une gate et n'est pas utilisé en routine. Il n'est autorisé qu'en cas de diagnostic de build corrompu, de contrainte disque explicite ou de demande ciblée, avec justification.
- **CMD-RUST-012** — La suppression manuelle de `target/` ne remplace pas `cargo clean` et suit les mêmes restrictions.
- **CMD-RUST-011** — `cargo clean` est l'outil canonique de remise à zéro complète du cache de build Cargo et peut être utilisé périodiquement pour maîtriser la taille de `../builds/sasedev-games/target`.
- **CMD-RUST-012** — Un nettoyage complet n'est pas exécuté à chaque delta. Il est planifié à un jalon de cycle approprié, normalement au démarrage de la première prerelease de développement lorsque l'ancien cache doit être évacué, ou au plus tard avant la validation finale RC/stable si l'accumulation disque le justifie.
- **CMD-RUST-013** — Entre deux nettoyages complets, les variantes ciblées de `cargo clean` (`-p`, `--release`, `--profile`, `--target`) sont préférées lorsqu'elles répondent au besoin de libération d'espace sans supprimer tout le cache.
- **CMD-RUST-014** — `cargo clean --dry-run --verbose` peut être utilisé pour estimer l'impact d'un nettoyage avant suppression.
- **CMD-RUST-015** — La suppression manuelle de `target/` ne remplace pas `cargo clean` et n'est utilisée qu'en diagnostic exceptionnel.
## Runners Desktop
@@ -46,7 +49,7 @@
- **CMD-ANDROID-001** — Les commandes Gradle Android sont exécutées depuis `Android/` ou avec un chemin explicite vers le wrapper du projet.
- **CMD-ANDROID-002** — Les tâches ciblées par application sont préférées, par exemple `./gradlew :game-reflex-poc:assembleDebug`, lorsqu'elles existent.
- **CMD-ANDROID-003** — Un build Android global n'est pas exécuté si la tranche ne touche ni Android ni le contrat natif utilisé par Android.
- **CMD-ANDROID-004** — `gradle clean` ou `./gradlew clean` n'est pas une gate normale et suit la même politique restrictive que `cargo clean`.
- **CMD-ANDROID-004** — `gradle clean` ou `./gradlew clean` reste un nettoyage Android ciblé ; il n'est pas rendu obligatoire uniquement parce qu'un `cargo clean` est planifié.
- **CMD-ANDROID-005** — Les commandes Android réelles ne deviennent des gates qu'après introduction du wrapper Gradle, de l'AGP, du NDK, de SDL3 et des modules exécutables correspondants.
## Web
@@ -67,7 +70,7 @@
- **CMD-BETA-001** — À l'entrée en beta, `scripts/audit_distribution_layout.py` vérifie les frontières statiques nécessaires aux runners et packagings supportés.
- **CMD-BETA-002** — La transition alpha vers beta exécute une suite Cargo workspace complète en plus des tests ciblés.
- **CMD-BETA-003** — Le build Tauri de packaging est lancé via `cargo tauri build`; ses hooks possèdent le build WASM et Vite/TypeScript.
- **CMD-BETA-003** — Si la version touche le périmètre Tauri, au moins un build de packaging beta est lancé via `cargo tauri build`; ses hooks possèdent le build WASM et Vite/TypeScript.
- **CMD-BETA-004** — Les APK Debug servent à la validation multi-appareils beta ; la signature de publication appartient à la phase RC/stable.
## RC et release
@@ -79,3 +82,9 @@
- **CMD-RC-005** — Android RC revalide au minimum x86_64 sur AVD et ARM64 sur appareil réel avec les APK issus de l'état RC.
- **CMD-RC-006** — Les secrets de signature, keystores et credentials de publication ne sont jamais commités. Leur présence est une condition externe de publication, pas une donnée du dépôt.
- **CMD-RC-007** — Une RC n'est promue en stable que si aucun correctif `.fix.N` n'est nécessaire après la gate RC complète.
## Matrice de validation
- **CMD-MATRIX-001** — `docs/rules/RULES_VALIDATION_MATRIX.md` associe des identifiants stables aux commandes et décrit leurs dépendances.
- **CMD-MATRIX-002** — Lorsqu'une modification affecte une crate dont dépendent d'autres crates, les validations ciblées couvrent la crate modifiée et les consommateurs directement ou transitivement impactés selon la portée de l'API.
- **CMD-MATRIX-003** — La matrice évolue avec le workspace ; ajouter une nouvelle plateforme ou un nouveau type de build doit ajouter ou adapter les commandes concernées plutôt que créer une procédure informelle parallèle.

16
docs/rules/RULES_DOCUMENTATION.md
View File

@@ -32,13 +32,23 @@
- **DOC-NAME-003** — Une fois un document livré, son numéro n'est pas renuméroté uniquement pour réordonner visuellement la documentation.
- **DOC-NAME-004** — Un statut n'est pas encodé dans le nom de fichier. Les changements de statut ne provoquent donc pas de renommage mécanique.
- **DOC-NAME-005** — Les noms de fichiers restent en anglais technique lorsqu'ils désignent un concept de projet ; le corps documentaire reste en français.
- **DOC-NAME-006** — Le `README.md` racine du dépôt conserve ce nom canonique. Les README imposés ou naturels à une crate/package peuvent également conserver `README.md`.
- **DOC-NAME-007** — Dans un répertoire documentaire destiné à contenir plusieurs fichiers Markdown, le point d'entrée porte le nom `000-README.md` afin d'être trié en premier.
- **DOC-NAME-008** — Un nouveau répertoire documentaire multi-fichiers ne crée pas de `README.md` concurrent à `000-README.md`.
## Listes de tâches et d'état
- **DOC-TASK-001** — Toute liste Markdown qui représente durablement des tâches, objectifs ou éléments suivis utilise les marqueurs `( )`, `(x)`, `(d)` et `(c)` plutôt que les task lists Markdown `[ ]` / `[x]`.
- **DOC-TASK-002** — `( )` signifie `planned`, `(x)` signifie `completed`, `(d)` signifie `deferred` et `(c)` signifie `cancelled`.
- **DOC-TASK-003** — Une liste purement descriptive n'utilise pas artificiellement ces marqueurs.
- **DOC-TASK-004** — Les règles spécialisées d'un document peuvent préciser la sémantique ou la traçabilité des marqueurs sans introduire un autre alphabet de statuts.
## ROADMAP
- **DOC-RMAP-001** — `ROADMAP.md` décrit le planning durable : objectifs prévus, réalisés, reportés ou annulés. Il ne suit pas le détail des prereleases et fixes.
- **DOC-RMAP-002** — Les marqueurs ROADMAP canoniques sont exclusivement `( )`, `(x)`, `(d)` et `(c)`. La syntaxe Markdown task-list `[ ]` / `[x]` n'est pas utilisée.
- **DOC-RMAP-003** — `( )` signifie `planned`, `(x)` signifie `completed`, `(d)` signifie `deferred` et `(c)` signifie `cancelled`.
- **DOC-RMAP-004** — Les marqueurs sont des statuts de lignes de scope, pas nécessairement un statut global de version.
- **DOC-RMAP-002** — Le ROADMAP utilise les marqueurs de suivi canoniques définis par `DOC-TASK-*`.
- **DOC-RMAP-003** — Les statuts s'appliquent aux lignes de scope et non automatiquement à une version entière.
- **DOC-RMAP-004** — Une version peut être entièrement décrite par une seule ligne ou être ventilée en plusieurs lignes lorsque son scope a plusieurs devenirs.
- **DOC-RMAP-005** — Une même version peut apparaître sur plusieurs lignes lorsque des sous-ensembles de son scope ont des devenirs différents.
- **DOC-RMAP-006** — Une ligne `(x)` décrit uniquement ce qui a effectivement été livré dans la version concernée.
- **DOC-RMAP-007** — Lorsqu'une partie du scope est reportée, elle reçoit sa propre ligne `(d)`. La destination est indiquée par `→ <version>` lorsqu'elle est connue, sinon par `→ target TBD`.

7
docs/rules/RULES_PROJECT.md
View File

@@ -75,3 +75,10 @@
- **GAME-PLATFORM-014** — Pour une launcher Activity Android racine, Back reste une navigation système. Le projet ne doit pas enregistrer de callback consommant Back uniquement pour logger ou exécuter de la logique métier ; sur API 36+, un `PRIORITY_SYSTEM_NAVIGATION_OBSERVER` peut observer l'action sans bloquer le Back-to-home.
- **GAME-PLATFORM-015** — Les exécutables Android initialisent le subscriber partagé et envoient les événements `tracing` vers logcat ; `stderr` n'est pas la destination Android de référence.
## Réservation de plateformes
- **GAME-PLATFORM-016** — Les familles de plateformes réservées sont Desktop, Mobile et Web. Desktop inclut potentiellement Linux, Windows et macOS ; Mobile inclut potentiellement Android et iOS.
- **GAME-PLATFORM-017** — Téléphone, tablette et futures classes de device sont des dimensions distinctes de l'OS et du backend technique.
- **GAME-PLATFORM-018** — SDL3 reste le backend natif de référence du POC, mais l'architecture de jeu ne doit pas assimiler une plateforme à SDL ni empêcher un adapter différent lorsque la plateforme l'exige.
- **GAME-PLATFORM-019** — Une plateforme réservée n'est ni implémentée ni planifiée tant qu'une ligne ROADMAP ou un delta ne l'engage explicitement.

65
docs/rules/RULES_VALIDATION_MATRIX.md Normal file
View File

@@ -0,0 +1,65 @@
<!-- file: docs/rules/RULES_VALIDATION_MATRIX.md -->
<!-- version: 1 -->
# Matrice normative des commandes et validations
## Principes
La matrice associe un identifiant stable à chaque famille de commandes. Le delta sélectionne les commandes applicables selon les fichiers touchés, leurs dépendances et la phase de maturité.
Une commande dépendante n'est exécutée que lorsque ses prérequis applicables sont propres.
Les commandes ciblées restent la norme pendant l'implémentation ; les gates workspace et les smokes de distribution deviennent plus larges à mesure que la version approche de beta/RC.
## Matrice
| ID | Commande / action | Dépend de | Déclencheur principal | Phase minimale typique |
|-----------|------------------------------------------------------------------------------------|-------------------------------------|--------------------------------------------|------------------------|
| `CMD-001` | `cargo fmt --all` | — | source Rust modifié | `pre` |
| `CMD-002` | `cargo fmt --all -- --check` | `CMD-001` si formatage requis | source Rust modifié | `pre` |
| `CMD-010` | `python3 scripts/audit_rust_workspace_rules.py` | — | Rust/workspace/règles Rust | `pre` |
| `CMD-011` | `python3 scripts/audit_markdown_tables.py ...` | — | Markdown/règles/docs | `pre` |
| `CMD-012` | `python3 scripts/audit_distribution_layout.py` | — | layout/build/distribution | `pre` |
| `CMD-020` | `cargo check -p <crate>` | `CMD-002`, `CMD-010` | crate Rust ciblée | `pre` |
| `CMD-021` | `cargo test -p <crate> --all-targets --all-features` | `CMD-020` | comportement/API crate | `pre` |
| `CMD-022` | tests des crates consommatrices impactées | `CMD-021` | API publique/contrat partagé modifié | `pre` |
| `CMD-023` | `cargo check --workspace` | audits applicables | changement transverse / gate globale | selon portée |
| `CMD-024` | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | `CMD-023` | gate complète | alpha/beta/RC |
| `CMD-025` | `cargo test --workspace --all-targets --all-features` | `CMD-024` | changement transverse / frontière de phase | beta/RC |
| `CMD-030` | build Desktop `--release` ciblé | gates Rust applicables | runner/distribution Desktop touché | beta |
| `CMD-031` | smoke Desktop release | `CMD-030` | runtime Desktop touché | beta |
| `CMD-040` | `cargo tauri build` | gates Rust/frontend applicables | périmètre Tauri touché | beta |
| `CMD-041` | smoke Tauri release | `CMD-040` | runtime Tauri touché | beta |
| `CMD-050` | build Rust Android ABI ciblé | gates Rust applicables | Android/JNI/backend natif touché | pre/beta |
| `CMD-051` | Gradle `assembleDebug` application ciblée | `CMD-050` lorsque Rust natif change | Android/app/manifest/Java touché | pre/beta |
| `CMD-052` | install + smoke AVD | `CMD-051` | Android concerné | beta |
| `CMD-053` | install + smoke appareil réel | `CMD-051` | Android concerné | beta/RC |
| `CMD-060` | `cargo clean --dry-run --verbose` | — | contrôle disque / préparation nettoyage | maintenance |
| `CMD-061` | `cargo clean` | décision explicite de nettoyage | accumulation disque / jalon de cycle | maintenance |
| `CMD-062` | `cargo clean -p <package>` ou nettoyage par `--release` / `--profile` / `--target` | — | nettoyage ciblé suffisant | maintenance |
## Dépendances entre crates
Lorsqu'une crate `A` change :
1. exécuter les validations ciblées de `A` ;
2. déterminer les consommateurs dont le contrat est affecté ;
3. exécuter les validations ciblées des consommateurs concernés ;
4. passer aux gates workspace lorsque la portée ne peut plus être bornée raisonnablement ou lorsqu'une frontière de maturité l'exige.
Une modification interne sans changement de contrat ne force pas mécaniquement tous les consommateurs transitifs à être retestés.
Une modification d'API publique, de représentation partagée, de feature structurante ou de comportement contractuel élargit la portée des tests.
## Nettoyage Cargo et contrôle disque
Le projet utilise `../builds/sasedev-games/target` comme `target-dir`. Cette zone peut accumuler plusieurs profils, triples cibles, artefacts incrémentaux et anciennes variantes au cours d'un cycle de développement.
La politique est donc double :
- utiliser `CMD-062` lorsqu'un nettoyage ciblé suffit ;
- utiliser `CMD-061` périodiquement afin d'éviter une croissance non bornée du répertoire de build.
Le nettoyage complet est normalement positionné au début d'un nouveau cycle de développement lorsque l'on souhaite évacuer les artefacts de la version précédente, ou avant une validation finale RC/stable lorsqu'un rebuild propre est recherché et que l'espace disque le justifie.
Le delta ou le plan de version indique quel jalon de nettoyage est retenu. Il n'est pas nécessaire d'exécuter `cargo clean` à chaque prerelease.

34
docs/rules/VERSION_WORKFLOW.md
View File

@@ -88,3 +88,37 @@ Les gates techniques sont proportionnelles aux fichiers touchés :
- une modification Tauri/frontend/build déclenche les gates correspondantes.
La promotion `rc` puis stable d'une version de conception exige une validation humaine explicite du contenu consolidé.
## Travail en RC
- **VER-RC-001** — Une RC est fonctionnellement gelée. Les nouvelles fonctionnalités, nouvelles capabilities, refactors architecturaux non indispensables et changements volontaires de comportement sont interdits.
- **VER-RC-002** — Les modifications de code restent autorisées en RC lorsqu'elles corrigent un bug, un test erroné, un défaut de packaging, un problème de sécurité, une incompatibilité de release ou un défaut strictement nécessaire à la publication.
- **VER-RC-003** — Un correctif conforme à `VER-RC-002` produit `3-rc.N.fix.M` et n'impose pas un retour automatique en beta.
- **VER-RC-004** — Si le périmètre fonctionnel est rouvert pendant une RC, la candidate est abandonnée et le développement revient à une phase adaptée, normalement beta, avant une nouvelle RC.
## Prompt de la version suivante
- **VER-PROMPT-001** — Le prompt de démarrage de la version suivante n'est pas créé à un numéro arbitraire de RC.
- **VER-PROMPT-002** — Sa génération devient recommandée après validation de la première RC dont le périmètre est effectivement gelé.
- **VER-PROMPT-003** — Le prompt peut être complété pendant les fixes RC ou la release stable, mais ne doit pas contenir de résultats futurs présentés comme déjà validés.
## Phases de développement
Une version de code suit conceptuellement :
```text
PLAN → IMPLEMENT → INTEGRATE → VALIDATE → CANDIDATE → RELEASE
```
- **VER-PHASE-001** — Ces phases structurent le travail mais n'imposent pas une prerelease distincte pour chacune.
- **VER-PHASE-002** — Une petite version peut combiner planification et première implémentation dans `0-pre.1`.
- **VER-PHASE-003** — Une version lourde peut réserver `0-pre.1` à la planification/décomposition et utiliser plusieurs `pre.N` pour l'implémentation avant alpha/beta.
- **VER-PHASE-004** — La phase de planification doit identifier le scope, les dépendances, les validations attendues et le découpage de livraison sans dupliquer le contenu normatif de ROADMAP, RULES ou de la matrice de commandes.
- **VER-PHASE-005** — La phase de validation vérifie l'état effectivement implémenté ; elle ne réécrit pas rétroactivement le plan initial.
## Versions Tauri/frontend
- **VER-TAURI-001** — Pour une app Tauri Rust du workspace, la version produit canonique est la version Cargo.
- **VER-TAURI-002** — `tauri.conf.json` omet `version` lorsque Tauri peut hériter de la version `Cargo.toml`.
- **VER-TAURI-003** — La `version` de `package.json` décrit le package frontend local et n'est pas synchronisée à chaque `pre.N` ou `.fix.N`.
- **VER-TAURI-004** — Tant que le frontend n'est pas publié comme package npm, sa version est mise à jour uniquement aux jalons significatifs retenus par le projet, au minimum lorsque cela est nécessaire pour alpha, beta, RC ou stable.

2
docs/studies/README.md → docs/studies/000-README.md
View File

@@ -1,4 +1,4 @@
<!-- file: docs/studies/README.md -->
<!-- file: docs/studies/000-README.md -->
<!-- version: 1 -->
# Études