diff --git a/Android/game-reflex-poc/build.gradle b/Android/game-reflex-poc/build.gradle index 13d61e8..40d3dc7 100644 --- a/Android/game-reflex-poc/build.gradle +++ b/Android/game-reflex-poc/build.gradle @@ -1,5 +1,5 @@ // file: Android/game-reflex-poc/build.gradle -// version: 27 +// version: 28 plugins { id 'com.android.application' @@ -18,7 +18,7 @@ android { minSdk 21 targetSdk 36 versionCode 2 - versionName '0.2.0-0-pre.1.fix.2' + versionName '0.2.0-0-pre.2' } compileOptions { diff --git a/Android/game-snake-poc/build.gradle b/Android/game-snake-poc/build.gradle index 9f5de18..51139e9 100644 --- a/Android/game-snake-poc/build.gradle +++ b/Android/game-snake-poc/build.gradle @@ -1,5 +1,5 @@ // file: Android/game-snake-poc/build.gradle -// version: 27 +// version: 28 plugins { id 'com.android.application' @@ -18,7 +18,7 @@ android { minSdk 21 targetSdk 36 versionCode 2 - versionName '0.2.0-0-pre.1.fix.2' + versionName '0.2.0-0-pre.2' } compileOptions { diff --git a/Cargo.toml b/Cargo.toml index 7577deb..c06594c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ # file: Cargo.toml -# version: 39 +# version: 40 [workspace] resolver = "3" @@ -19,7 +19,7 @@ members = [ ] [workspace.package] -version = "0.2.0-0-pre.1.fix.2" +version = "0.2.0-0-pre.2" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/games" diff --git a/README.md b/README.md index cab5b84..18c3e9a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # games.sasedev @@ -25,7 +25,7 @@ Workspace expérimental puis productif pour des jeux multiplateformes principale Version stable de référence : `0.1.0`. -Version candidate en cours de conception : `0.2.0-0-pre.1.fix.2`. +Version candidate en cours de conception : `0.2.0-0-pre.2`. Les deux premiers jeux sont des POC structurels : `game-reflex-poc` et `game-snake-poc`. Ils existent d'abord pour valider les frontières du workspace, le moteur, les assets et le packaging multiplateforme. diff --git a/ROADMAP.md b/ROADMAP.md index 64b1c5f..2b6125f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap @@ -24,7 +24,7 @@ Le détail historique des prereleases `0.1.0-*` reste dans `deltas/0.1.0/` et `h ## 0.2.0 — Conception du framework modulaire -- ( ) `0.2.0` — fixer la gouvernance documentaire, la nomenclature et le cycle de maturation des idées et décisions. +- (x) `0.2.0` — fixer la gouvernance documentaire, la nomenclature et le cycle de maturation des idées et décisions. - ( ) `0.2.0` — inventorier et réserver les capabilities déjà justifiées sans les implémenter prématurément. - ( ) `0.2.0` — définir les couches, les dépendances autorisées et la frontière entre kernel, capability, plateforme, provider, système de jeu et service. - ( ) `0.2.0` — établir la matrice plateformes et les archétypes de jeux utilisés pour challenger l'architecture. diff --git a/deltas/0.2.0/0-pre.2.md b/deltas/0.2.0/0-pre.2.md new file mode 100644 index 0000000..ea31677 --- /dev/null +++ b/deltas/0.2.0/0-pre.2.md @@ -0,0 +1,65 @@ + + + +# Delta 0.2.0-0-pre.2 + +## Base + +Base déclarée : `0.2.0-0-pre.1.fix.2`. + +## Objet + +Étudier les fonctionnalités plausibles déjà justifiées et leur ownership architectural sans encore planifier les POC techniques ni le premier projet réel. + +## Contenu + +- enregistrement du jalon `0-pre.1.fix.2` validé dans `history/` ; +- inventaire fonctionnel initial ; +- distinction kernel / technical capability / game-system / platform adapter / provider / server service / tooling / game-specific ; +- étude des axes OS, device, execution model, host et backend ; +- pressure test par plusieurs archétypes de jeux ; +- étude des dépendances et de la composition statique ; +- conservation de macOS/iOS comme plateformes réservées ; +- absence volontaire de création de nouvelles crates. + +## Hors scope + +Cette prerelease ne : + +- fige pas encore l'architecture normative ; +- ne crée pas le manifest produit définitif ; +- ne planifie pas encore le POC Tauri Android ; +- ne planifie pas le premier jeu réel ; +- n'implémente aucune capability ; +- ne crée aucune nouvelle crate runtime. + +## Validation automatique + +```bash +python3 scripts/audit_rust_workspace_rules.py +python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android deltas history +python3 scripts/audit_distribution_layout.py +``` + +Aucune gate Cargo/Gradle/smoke n'est requise par le contenu fonctionnel de cette tranche : aucun code runtime ou build n'est modifié. + +## Validation humaine + +Relire en priorité : + +- `docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md` ; +- `docs/studies/002-LAYERING_AND_OWNERSHIP_STUDY.md` ; +- `docs/studies/003-PLATFORM_CAPABILITY_STUDY.md` ; +- `docs/studies/004-GAME_ARCHETYPE_PRESSURE_TEST.md` ; +- `docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md`. + +La revue doit notamment signaler : + +- fonctionnalités manquantes ; +- fonctionnalités sur-réservées ; +- mauvais ownership ; +- dépendances trop fortes ; +- confusion entre capability et game-system ; +- limites plateforme oubliées. + +Les décisions retenues seront seulement ensuite promues vers `docs/architecture/`. diff --git a/docs/studies/000-README.md b/docs/studies/000-README.md index af780b0..0f37a93 100644 --- a/docs/studies/000-README.md +++ b/docs/studies/000-README.md @@ -1,5 +1,5 @@ - + # Études @@ -15,3 +15,13 @@ Une étude reste non normative. Elle peut conclure notamment à : Une conclusion `retained` ne crée pas à elle seule une règle, une capability ou une entrée de roadmap. La décision résultante doit être portée explicitement dans le document architectural ou normatif approprié. Les études conservent les alternatives et raisons utiles à la compréhension future, y compris lorsqu'une piste est rejetée. + +## Études 0.2.0 + +- [`001-FUNCTIONAL_CAPABILITY_INVENTORY.md`](001-FUNCTIONAL_CAPABILITY_INVENTORY.md) — inventaire fonctionnel initial sans engagement d'implémentation. +- [`002-LAYERING_AND_OWNERSHIP_STUDY.md`](002-LAYERING_AND_OWNERSHIP_STUDY.md) — étude du découpage kernel, capability, game-system, plateforme, provider, service et jeu. +- [`003-PLATFORM_CAPABILITY_STUDY.md`](003-PLATFORM_CAPABILITY_STUDY.md) — axes plateforme/device/host/backend et disponibilité des capacités. +- [`004-GAME_ARCHETYPE_PRESSURE_TEST.md`](004-GAME_ARCHETYPE_PRESSURE_TEST.md) — vérification du modèle par plusieurs familles de jeux. +- [`005-DEPENDENCY_AND_COMPOSITION_STUDY.md`](005-DEPENDENCY_AND_COMPOSITION_STUDY.md) — dépendances autorisées et composition statique envisagée. + +Ces études sont des propositions à relire. Elles ne deviennent pas automatiquement des décisions d'architecture. diff --git a/docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md b/docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md new file mode 100644 index 0000000..c9648f5 --- /dev/null +++ b/docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md @@ -0,0 +1,377 @@ + + + +# Inventaire fonctionnel initial + +## Statut + +Étude non normative pour `0.2.0-0-pre.2`. + +Le but est d'identifier les besoins plausibles déjà justifiés par les jeux et plateformes envisagés. La présence d'une entrée ne signifie ni crate à créer, ni API figée, ni version d'implémentation engagée. + +## Principe de classement + +Chaque besoin doit finir dans l'une des familles suivantes : + +- **kernel** — primitive minimale nécessaire au fonctionnement générique du moteur ; +- **technical capability** — service technique réutilisable exposé au jeu ; +- **game-system** — mécanique de gameplay réutilisable entre plusieurs jeux ; +- **platform adapter** — implémentation d'un contrat pour un OS, host ou backend ; +- **provider** — intégration d'un service externe interchangeable ; +- **server service** — autorité ou service distant partagé ; +- **tooling** — construction, génération, validation ou distribution ; +- **game-specific** — règle propre à un jeu qui ne doit pas être généralisée prématurément. + +## Kernel candidat + +Le kernel doit rester volontairement petit. + +Candidats déjà justifiés : + +- lifecycle générique `start / update / render / stop` ; +- horloge monotone et temps de frame ; +- fixed-step ou scheduling déterministe lorsque requis ; +- abstraction d'événements/runtime sans dépendance directe au jeu ; +- contexte runtime/provenance déjà introduit en `0.1.0` ; +- contrats minimaux nécessaires pour connecter input et rendu ; +- politique de quit/lifecycle indépendante de SDL/Android/Tauri. + +À challenger avant décision : + +- scene stack ; +- scheduler générique ; +- ECS ; +- task graph ; +- event bus généraliste. + +Ces éléments ne doivent pas être réservés uniquement parce qu'ils sont courants dans d'autres moteurs. + +## Technical capabilities candidates + +### Input + +Besoins identifiés : + +- actions sémantiques indépendantes des touches physiques ; +- clavier ; +- souris/pointer ; +- tactile ; +- gestes ; +- contrôles virtuels affichés ; +- gamepad ; +- bindings configurables ; +- profils par produit et plateforme ; +- multi-player local avec plusieurs périphériques lorsque le jeu le demande. + +Le jeu consomme des actions telles que `MoveUp`, `PrimaryAction` ou `Pause`, pas `KeyW` ou `SwipeUp`. + +### Rendering + +Besoins identifiés : + +- dessin 2D ; +- sprites ; +- textures ; +- texte ; +- viewport/résolution virtuelle ; +- caméra 2D pour cartes plus grandes que l'écran ; +- couches/z-order ; +- animation sprite-sheet ; +- primitives simples de debug. + +La 3D n'est pas réservée à ce stade. + +### Audio + +Besoins identifiés : + +- effets sonores ; +- musique ; +- volume/mute ; +- lifecycle audio mobile ; +- éventuellement groupes/bus simples. + +La voix temps réel reste une idée/étude future liée à un cas de jeu concret. + +### Assets + +Besoins identifiés : + +- assets embarqués ; +- assets communs et propres au jeu ; +- résolution logique des chemins ; +- variantes par densité/résolution si nécessaire ; +- téléchargement/cache d'assets distants pour certains jeux futurs ; +- intégrité/version d'asset lorsqu'un CDN sera réellement introduit. + +### Persistence locale + +Besoins identifiés : + +- préférences ; +- save-game ; +- progression locale ; +- cache ; +- journal/outbox pour online-optional à terme. + +Les garanties exactes de transaction, migration et chiffrement seront étudiées quand un jeu les exigera. + +### Networking client + +Besoins identifiés : + +- HTTP(S) ; +- WebSocket ; +- reconnexion ; +- timeout/backoff ; +- protocole versionné côté jeu/service ; +- état de connectivité ; +- séparation transport/protocole. + +WebRTC et gRPC restent des solutions à étudier pour des usages précis et ne sont pas imposés au framework général. + +### Logging/diagnostics + +Besoins identifiés : + +- `tracing` commun ; +- domaines par crate/sous-système ; +- niveau maximal déterminé par produit/build ; +- filtrage runtime dans la limite de ce qui a été compilé ; +- logs Android/logcat, Desktop et Tauri ; +- métriques/telemetry ultérieures sans les confondre avec le logging. + +### Identity/auth client + +Besoins identifiés : + +- joueur anonyme ; +- compte requis ; +- upgrade anonyme vers compte ; +- identité canonique propre au backend ; +- liaison d'identités externes ; +- session/token ; +- déconnexion et changement de compte. + +Google, Play Games, Apple, Steam ou autres sont des providers, pas l'identité canonique du moteur. + +### Monetization client + +Besoins identifiés : + +- rewarded ad ; +- interstitial éventuel selon jeu ; +- disponibilité/cooldown ; +- résultat `completed / skipped / failed / unavailable` ; +- absence complète de monétisation sur certaines plateformes/produits ; +- achats intégrés futurs si un jeu en a besoin. + +Les régies spécifiques restent des providers. + +## Game-systems candidats + +### Score et objectifs + +- score ; +- combo/multiplicateur ; +- chronomètre ; +- objectifs ; +- calcul de résultat final. + +Le calcul exact reste contrôlé par le jeu. + +### Lives / attempts + +- nombre de vies ou tentatives ; +- consommation/restauration ; +- politique de game-over ; +- recharge éventuelle. + +### Energy / stamina + +- réserve courante/maximale ; +- coût d'action ; +- recharge temporelle ; +- recharge par reward/ad/inventory ; +- politique offline éventuelle. + +### Progression / XP / levels + +- expérience ; +- niveaux ; +- seuils ; +- progression débloquée ; +- récompenses de niveau. + +La notion de « level » de progression ne doit pas être confondue avec une map/stage. + +### Inventory / items + +- item type/id ; +- quantité ; +- capacité ; +- acquisition/consommation ; +- metadata de gameplay ; +- sérialisation. + +Équipement, crafting, rareté ou économie ne sont pas imposés au noyau inventaire tant qu'un jeu ne les exige pas. + +### Grid / tile map + +Besoins identifiés par Snake, Sokoban et aventure puzzle : + +- coordonnées de grille ; +- taille de cellule ; +- occupancy ; +- tile map ; +- couches ; +- obstacles ; +- wrap/no-wrap ; +- spawn zones ; +- chargement de map. + +### Collision 2D + +Plusieurs niveaux possibles : + +- collision grille/cellule ; +- AABB ; +- formes simples ; +- collision continue/physique avancée. + +Seules les collisions réellement nécessaires seront implémentées. Un moteur physique généraliste n'est pas réservé à ce stade. + +### Determinism / seeded challenge + +Besoins identifiés par Reflex compétitif et potentiellement puzzles/races : + +- seed ; +- ruleset versionné ; +- génération reproductible ; +- horodatage relatif ; +- replay ou validation partielle ultérieure. + +### Puzzle systems + +Systèmes potentiellement réutilisables, mais à ne créer qu'après second consommateur ou besoin clair : + +- Sokoban-like push blocks ; +- pipe/plumber connectivity ; +- laser/mirror ray routing ; +- switches/doors ; +- collect-and-unlock. + +### Navigation/map progression + +Pour aventure/puzzle : + +- stages/maps ; +- transitions ; +- checkpoints ; +- unlock graph. + +À distinguer du `Progression/XP`. + +### Racing systems + +Candidats si un projet racing est lancé : + +- checkpoints ; +- laps ; +- start grid ; +- race timer ; +- classement en course ; +- ghost/replay ; +- synchronisation multiplayer. + +La physique de véhicule reste hors du framework général tant qu'elle n'est pas justifiée. + +### Combat systems + +Candidats pour fighting/hack'n slash/MMORPG : + +- health/damage ; +- cooldown ; +- hit/hurt boxes ; +- status effects ; +- abilities ; +- target selection. + +Ils ne sont pas réservés comme API aujourd'hui ; ils identifient seulement une pression architecturale future. + +## Platform adapters candidates + +Les adapters implémentent les contrats techniques sans contenir la logique de jeu. + +Cibles déjà identifiées ou réservées : + +- SDL3 native Desktop ; +- SDL3 Android ; +- Web/WASM ; +- Tauri Desktop host ; +- Tauri Android host expérimental futur ; +- macOS natif réservé ; +- iOS natif réservé. + +L'OS, la classe de device, l'execution model et le host restent des dimensions distinctes. + +## Providers candidates + +Providers externes déjà justifiés par les objectifs : + +- ads : AdMob, puis autres régies si besoin ; +- identity : Google/OAuth, Play Games, Apple/Steam ultérieurement selon plateforme ; +- leaderboard : backend propre et/ou provider plateforme ; +- cloud storage : backend propre ; +- assets/CDN : provider de stockage/CDN ; +- paiement/IAP : stores plateforme ; +- crypto reward/wallet : provider isolé uniquement pour un projet PKE concerné. + +Aucun provider ne doit remonter dans le kernel. + +## Server services candidates + +Besoins identifiés : + +- auth/identity ; +- profile ; +- save/progression cloud ; +- leaderboard ; +- match/lobby ; +- realtime authoritative session ; +- chat éventuel ; +- asset metadata/CDN orchestration ; +- administration/modération selon besoins ; +- anti-cheat/validation serveur pour compétitif ; +- économie/reward authority pour tout jeu avec valeur monétaire ou crypto. + +Le déploiement peut commencer comme modular monolith sans imposer le découpage physique initial. + +## Tooling candidates + +Besoins identifiés : + +- build Android multi-ABI ; +- orchestration Desktop/Tauri/Web ; +- packaging ; +- génération de manifests produit ; +- validation de dépendances/capabilities ; +- génération de configuration logging ; +- génération/validation assets ; +- outils de map/level seulement lorsqu'un jeu concret en a besoin. + +## Hors réservation actuelle + +Ne sont pas réservés comme capacités du framework à ce stade : + +- rendu 3D ; +- moteur physique 3D ; +- VR/AR ; +- voice chat ; +- procedural world massif ; +- scripting embarqué généraliste ; +- plugin runtime dynamique par `.so`/`.dll` ; +- marketplace générique ; +- NFT. + +Ces sujets peuvent devenir des idées/études si un futur projet les justifie. diff --git a/docs/studies/002-LAYERING_AND_OWNERSHIP_STUDY.md b/docs/studies/002-LAYERING_AND_OWNERSHIP_STUDY.md new file mode 100644 index 0000000..430af7b --- /dev/null +++ b/docs/studies/002-LAYERING_AND_OWNERSHIP_STUDY.md @@ -0,0 +1,240 @@ + + + +# Étude du layering et de l'ownership + +## Statut + +Étude non normative pour `0.2.0-0-pre.2`. + +## Problème + +Le framework doit permettre plusieurs jeux et plateformes sans transformer `engine-v1` en monolithe ni multiplier prématurément les crates. + +Le classement proposé repose sur la question : + +> qui possède la règle et qui peut légitimement la réutiliser ? + +## 1. Engine kernel + +Responsabilités candidates : + +- lifecycle ; +- temps/scheduling minimal ; +- orchestration générique update/render ; +- contrats minimaux entre runtime et jeu ; +- provenance runtime ; +- quit/lifecycle générique. + +Le kernel ne connaît pas : + +- score ; +- vies ; +- inventaire ; +- ads ; +- auth ; +- leaderboard ; +- maps propres au jeu ; +- WebSocket ; +- provider externe ; +- règles Snake/Reflex. + +## 2. Technical capability + +Une technical capability fournit un service technique générique au jeu ou à un game-system. + +Exemples : + +- input ; +- render ; +- audio ; +- assets ; +- persistence ; +- network transport ; +- logging ; +- identity client ; +- ads client. + +Pattern candidat : + +```text +capability API + ↑ +game / game-system + ↓ +adapter/provider implementation +``` + +Une capability n'impose pas qu'une crate existe immédiatement. + +## 3. Game-system + +Un game-system encapsule une mécanique de gameplay réutilisable. + +Exemples plausibles : + +- score ; +- lives ; +- energy ; +- progression/XP ; +- inventory ; +- grid/tile map ; +- collision simple ; +- seeded challenge ; +- puzzle primitives. + +Un game-system peut dépendre de capabilities techniques mais ne doit pas dépendre d'une app plateforme. + +Exemple : + +```text +energy-system + ↓ +clock capability + ↓ +reward contract +``` + +Il ne doit pas appeler directement AdMob. + +## 4. Platform adapter + +Un adapter traduit une plateforme/backend vers une technical capability. + +Exemples : + +```text +input-api + ├─ sdl-keyboard adapter + ├─ sdl-touch adapter + └─ web-pointer adapter +``` + +ou : + +```text +render-api + ├─ sdl renderer + └─ web renderer +``` + +Un adapter peut être propre à une plateforme ou partagé par plusieurs plateformes lorsque le backend le permet. + +## 5. Provider + +Un provider intègre un service externe interchangeable. + +Exemples : + +- AdMob ; +- Google OAuth ; +- Play Games ; +- Apple Game Center éventuel ; +- backend leaderboards ; +- CDN. + +Différence avec platform adapter : + +- adapter = traduit un environnement technique local ; +- provider = parle à un service ou SDK externe pouvant être substitué. + +Un provider peut lui-même être platform-specific. + +## 6. Server service + +Le serveur possède les décisions qui ne peuvent pas être fiables côté client lorsqu'il existe un enjeu partagé ou compétitif. + +Exemples : + +- identité canonique ; +- leaderboard validé ; +- matchmaking ; +- session realtime authoritative ; +- récompense à valeur économique ; +- résolution de conflits cloud ; +- anti-cheat. + +Le client conserve les responsabilités locales nécessaires au fonctionnement offline lorsque le produit l'autorise. + +## 7. Game-specific + +La règle reste dans le jeu lorsque sa généralisation n'est pas démontrée. + +Exemples actuels : + +- croissance et corps du Snake ; +- génération de séquence Reflex ; +- règle exacte d'apparition/disparition des cibles ; +- coût précis pour creuser une case dans un jeu d'aventure ; +- moveset d'un personnage de fighting. + +Règle candidate : + +> un second besoin similaire peut justifier l'extraction d'un game-system ; un seul cas ne suffit pas automatiquement. + +## 8. Tooling + +Le tooling construit ou valide le produit mais n'entre pas dans le runtime du jeu. + +Exemples : + +- builder Android multi-ABI ; +- packaging ; +- génération de config ; +- audit manifests/capabilities ; +- outils de contenu. + +## Frontières proposées + +### À éviter + +```text +game -> AdMob SDK +game -> Java Android +game -> Tauri command +game -> tokio-tungstenite +game -> filesystem OS direct +``` + +### Préféré + +```text +game + ↓ +capability / game-system + ↓ +adapter/provider + ↓ +platform/external service +``` + +## API / façade / implémentation + +Lorsque la complexité le justifie, une famille peut suivre : + +```text +-api +-lib +--lib +``` + +Mais cette structure ne doit pas être créée par réflexe. + +Critères pour créer plusieurs crates : + +- plusieurs implémentations ; +- besoin de dépendance inversée ; +- frontière de compilation/platforme ; +- dépendances lourdes que certains produits doivent éviter ; +- tests/ownership clairement séparés. + +Sinon une seule crate réutilisable peut suffire. + +## Questions à trancher plus tard + +- `render` doit-il rester dans `engine-v1-sdl` ou devenir une capability explicite ? +- `input` doit-il être un domaine autonome dès `0.2.x` ? +- score/lives/energy doivent-ils être regroupés dans une crate `gameplay-common` ou rester séparés ? +- grid/map/collision simple doivent-ils partager une famille de crates ? +- networking doit-il être une technical capability ou une famille `networking/` distincte au workspace ? +- où placer la frontière entre client auth générique et provider OAuth ? diff --git a/docs/studies/003-PLATFORM_CAPABILITY_STUDY.md b/docs/studies/003-PLATFORM_CAPABILITY_STUDY.md new file mode 100644 index 0000000..b3a0ff2 --- /dev/null +++ b/docs/studies/003-PLATFORM_CAPABILITY_STUDY.md @@ -0,0 +1,148 @@ + + + +# Étude plateforme et disponibilité des capacités + +## Statut + +Étude non normative pour `0.2.0-0-pre.2`. + +## Axes indépendants + +Une cible produit ne doit pas être décrite par un seul enum « platform ». + +Axes candidats : + +### OS / environnement + +- Linux ; +- Windows ; +- macOS ; +- Android ; +- iOS ; +- Browser/Web. + +### Device class + +- Desktop ; +- Phone ; +- Tablet ; +- Unknown. + +D'autres classes ne sont ajoutées qu'avec un besoin réel. + +### Execution model + +- Native ; +- Wasm. + +### Runtime host + +- Native ; +- Browser ; +- TauriWebView. + +### Backend + +Exemples actuels : + +- SDL3 ; +- Web APIs via WASM ; +- Tauri host + frontend Web/WASM. + +Le backend n'est pas l'identité du jeu. + +## Cibles connues + +| Cible | OS/environnement | Device | Execution | Host | Backend principal | +| --- | --- | --- | --- | --- | --- | +| Desktop SDL Linux | Linux | Desktop | Native | Native | SDL3 | +| Desktop SDL Windows | Windows | Desktop | Native | Native | SDL3 | +| Desktop SDL macOS | macOS | Desktop | Native | Native | SDL3, réservé | +| Android SDL | Android | Phone/Tablet | Native | Native | SDL3 + Java/JNI | +| iOS natif | iOS | Phone/Tablet | Native | Native | réservé | +| Web | Browser | Desktop/Phone/Tablet | Wasm | Browser | Web/WASM | +| Tauri Desktop | Linux/Windows/macOS | Desktop | Wasm côté jeu POC | TauriWebView | Tauri + Web/WASM | +| Tauri Android | Android | Phone/Tablet | à étudier | TauriWebView | expérimental futur | + +## Capacités et variabilité + +### Input + +Desktop : + +- clavier ; +- souris ; +- gamepad éventuel. + +Mobile : + +- tactile ; +- gestes ; +- contrôles virtuels ; +- gamepad éventuel. + +Web : + +- clavier/pointer/touch selon device ; +- browser restrictions. + +Le mapping physique appartient à l'adapter/profil, pas au jeu. + +### Storage + +Native : + +- filesystem/app storage possible selon OS. + +Web : + +- stockage navigateur et quotas spécifiques. + +Le jeu doit consommer un contrat logique et non un chemin OS. + +### Ads et IAP + +Disponibilité dépendante du produit, de la plateforme et du provider. + +Un produit Desktop ou Web peut volontairement déclarer Ads `unsupported` ou `disabled` même si le framework possède une capability Ads. + +### Identity plateforme + +Play Games, Apple/Game Center ou services similaires sont des providers de plateforme. Aucun n'est requis pour définir un `PlayerId` canonique. + +### Networking + +HTTP/WebSocket sont plausibles sur toutes les grandes cibles mais leur implémentation et restrictions diffèrent. + +Le protocole métier reste indépendant du transport. + +## Politique de disponibilité candidate + +Une capability produit peut être : + +- `required` ; +- `optional` ; +- `disabled` ; +- `unsupported` ; +- `server-required`. + +Cette liste devra être challengée lors de l'étude du manifest produit. + +## SDL comme point d'entrée natif + +SDL3 est le backend natif de référence actuel parce qu'il permet de réutiliser une grande partie du runtime entre Desktop et Android et réserve une trajectoire macOS/iOS. + +Cette décision ne doit pas devenir : + +> tous les produits doivent obligatoirement utiliser SDL. + +Le POC Tauri Android servira précisément à comparer un second chemin de packaging/host sans modifier les règles de gameplay. + +## Questions ouvertes + +- support iOS : SDL natif seul, Tauri mobile, ou coexistence ? +- rendu Web : abstraction SDL-like ou renderer Web dédié ? +- gamepad mobile/web : capability immédiate ou réservation ? +- filesystem et save-game : API unique avec garanties minimales ou contrats spécialisés ? +- quelles capabilities doivent être détectables au runtime et lesquelles doivent être décidées au build ? diff --git a/docs/studies/004-GAME_ARCHETYPE_PRESSURE_TEST.md b/docs/studies/004-GAME_ARCHETYPE_PRESSURE_TEST.md new file mode 100644 index 0000000..6bf174a --- /dev/null +++ b/docs/studies/004-GAME_ARCHETYPE_PRESSURE_TEST.md @@ -0,0 +1,185 @@ + + + +# Pressure test par archétypes de jeux + +## Statut + +Étude non normative pour `0.2.0-0-pre.2`. + +Le but n'est pas de planifier tous ces jeux. Ils servent à vérifier que l'architecture envisagée ne fonctionne pas uniquement pour Reflex et Snake. + +## Reflex compétitif + +Besoins : + +- input pointer/touch ; +- rendu 2D ; +- timer précis ; +- génération déterministe par seed/ruleset ; +- score ; +- leaderboard ; +- auth optionnelle ou obligatoire selon mode ; +- soumission de résultats ; +- validation serveur potentielle. + +Conclusion provisoire : + +Reflex pousse surtout sur déterminisme, input abstrait, score et backend compétitif. + +## Snake configurable + +Besoins : + +- grid/tile map ; +- input sémantique ; +- sprites head/body/tail ; +- obstacles ; +- wrap/no-wrap ; +- self-collision ; +- plusieurs snakes ; +- vitesse/ruleset configurable ; +- maps ; +- score/lives ; +- AI éventuelle ; +- multiplayer 2 joueurs éventuel. + +Conclusion provisoire : + +Snake est un bon candidat pour valider `grid`, `collision simple`, configuration de règles et séparation single-player/multiplayer. + +## Aventure puzzle à énergie + +Référence fonctionnelle : jeu d'exploration/puzzle avec énergie, cartes et mini-puzzles. + +Besoins : + +- map/tile ; +- énergie ; +- inventaire ; +- progression/XP ; +- niveaux/stages ; +- save-game ; +- account/cloud sync ; +- rewarded ads ; +- puzzle systems ; +- leaderboard ou événements compétitifs éventuels ; +- assets distants possibles. + +Conclusion provisoire : + +cet archétype exerce fortement les game-systems et services sans exiger du temps réel multijoueur. + +## Puzzle Sokoban / pipe / laser + +Besoins : + +- grid ; +- occupancy ; +- deterministic rules ; +- undo/restart ; +- map format ; +- objectifs ; +- éventuellement éditeur de niveaux. + +Conclusion provisoire : + +les puzzles doivent pouvoir partager des primitives sans transformer chaque règle en capability globale. + +## Racing 2–4 joueurs + +Besoins : + +- input faible latence ; +- simulation ; +- checkpoints/laps ; +- interpolation/prediction éventuelle ; +- matchmaking/lobby ; +- session realtime ; +- serveur authoritative pour compétition ; +- reconnect/spectator éventuellement ; +- leaderboard. + +Conclusion provisoire : + +le networking temps réel doit rester séparé du kernel et du transport généraliste. + +## Fighting 1v1 + +Besoins : + +- input précis ; +- animation ; +- hit/hurt boxes ; +- health ; +- move/state machine ; +- rollback ou autre stratégie réseau si online compétitif ; +- matchmaking. + +Conclusion provisoire : + +l'architecture doit permettre un runtime spécialisé sans imposer ses contraintes de rollback à tous les jeux. + +## Hack'n slash + +Besoins : + +- map/collision ; +- combat ; +- inventory/equipment ; +- progression ; +- AI ; +- save ; +- online optionnel ou co-op selon produit. + +Conclusion provisoire : + +combat/inventory/progression doivent pouvoir être combinés sans appartenir au kernel. + +## MMORPG + +Besoins potentiels : + +- auth obligatoire ; +- monde persistant ; +- inventory/economy ; +- serveur authoritative ; +- zones/instances ; +- chat ; +- parties/guildes éventuelles ; +- patch/assets distants ; +- anti-cheat ; +- observability serveur. + +Conclusion provisoire : + +ce cas impose une architecture client/serveur nettement plus large mais ne doit pas gonfler l'engine local avant qu'un tel projet soit réellement lancé. + +## PKE avec reward crypto éventuel + +Besoins supplémentaires : + +- identité forte ; +- wallet/provider isolé ; +- reward authority ; +- audit/anti-fraud ; +- conformité et sécurité ; +- séparation stricte entre gameplay et intégration crypto. + +Conclusion provisoire : + +la crypto n'est jamais une capability fondamentale du moteur. Elle appartient à un provider/service d'un produit spécifique. + +## Résultat du pressure test + +Le modèle semble devoir supporter au minimum : + +- kernel minimal ; +- technical capabilities composables ; +- game-systems réutilisables ; +- adapters de plateforme ; +- providers externes ; +- services serveur ; +- règles propres à chaque jeu. + +Aucun archétype étudié ne justifie à ce stade un engine monolithique contenant directement inventaire, ads, auth ou networking realtime. diff --git a/docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md b/docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md new file mode 100644 index 0000000..2af7917 --- /dev/null +++ b/docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md @@ -0,0 +1,174 @@ + + + +# Étude des dépendances et de la composition + +## Statut + +Étude non normative pour `0.2.0-0-pre.2`. + +## Objectif + +Permettre qu'un produit choisisse uniquement ce dont il a besoin, sans duplication des jeux et sans couplage aux providers/platformes. + +## Dépendances proposées + +Direction générale : + +```text +game-specific + ↓ +game-systems + ↓ +technical capability APIs + ↓ +engine kernel contracts +``` + +Les implémentations sont injectées/composées par le produit : + +```text +app/product + ├─ game + ├─ adapters + ├─ providers + └─ runtime/backend +``` + +Le jeu ne choisit pas lui-même son provider AdMob, son adapter Android ou son transport concret. + +## Dépendances interdites candidates + +- kernel → game ; +- kernel → provider ; +- game-system → application plateforme ; +- game → SDK publicitaire ; +- game → Java Android ; +- game → Tauri ; +- provider → game-specific ; +- serveur générique → crate d'application client. + +Des exceptions ne doivent être introduites qu'après justification explicite. + +## Composition statique + +La direction proposée reste la composition Rust statique. + +Exemple conceptuel : + +```text +game-snake-android + ├─ game-snake + ├─ engine-v1-... + ├─ input-touch adapter + ├─ render-sdl adapter + ├─ logging-android + └─ ads-admob provider [si activé] +``` + +Un autre produit : + +```text +game-snake-desktop + ├─ game-snake + ├─ engine-v1-... + ├─ input-keyboard adapter + ├─ render-sdl adapter + └─ no ads provider +``` + +Le gameplay reste le même. + +## Cargo features + +Les features Cargo restent utiles pour : + +- capacités locales d'une crate ; +- optional dependencies ; +- sélection technique bornée. + +Elles ne doivent pas devenir le langage global de composition du produit, car leur unification à travers le graphe peut rendre les variantes difficiles à raisonner. + +## Manifest produit/jeu + +Un manifest dédié pourra décrire plus tard : + +- engine generation ; +- plateformes ; +- capabilities requises ; +- capabilities optionnelles ; +- providers ; +- online policy ; +- input profiles ; +- asset packs ; +- logging profile. + +Exemple purement illustratif : + +```toml +[product] +game = "snake" +engine = "v1" + +[capabilities] +score = "required" +auth = "optional" +ads = "disabled" +online = "optional" + +[platforms] +desktop = true +android = true +web = true +``` + +Ce format n'est pas encore retenu. + +## Crates : création à la demande + +Un concept réservé n'entraîne pas automatiquement une crate. + +Créer une crate devient justifié notamment si : + +- plusieurs consommateurs réels existent ; +- une dépendance lourde doit être isolée ; +- plusieurs providers/adapters sont nécessaires ; +- une frontière platform-specific est requise ; +- un contrat stable mérite une API séparée. + +## Structure workspace candidate + +La structure pourrait évoluer vers des familles comme : + +```text +crates/ + engines/ + capabilities/ + game-systems/ + providers/ + networking/ + games/ + apps/ + servers/ + common/ + tools/ +``` + +Cette arborescence est une hypothèse d'étude. Elle n'est pas encore un contrat de fichiers. + +## Online/offline + +La composition doit pouvoir exprimer : + +- offline-only ; +- online-optional ; +- online-required ; +- online-required pour une capability particulière. + +Un jeu online-optional ne doit pas avoir à compiler tout un stack realtime s'il n'en a pas besoin. + +## Étape suivante après validation de l'étude + +Après revue de `0-pre.2`, les décisions retenues pourront être promues progressivement vers `docs/architecture/`. + +Ce n'est qu'après cette promotion qu'il sera pertinent de planifier les POC techniques, notamment Tauri Android, Web/WASM et les variantes natives, pour tester les hypothèses de plateforme. diff --git a/history/0.2.0/0-pre.1.fix.2.md b/history/0.2.0/0-pre.1.fix.2.md new file mode 100644 index 0000000..023016f --- /dev/null +++ b/history/0.2.0/0-pre.1.fix.2.md @@ -0,0 +1,29 @@ + + + +# Historique 0.2.0-0-pre.1.fix.2 + +## Statut + +Jalon de gouvernance documentaire accepté avant ouverture de `0.2.0-0-pre.2`. + +## Décisions validées + +- séparation `ideas / studies / architecture / rules` ; +- points d'entrée documentaires `000-README.md` ; +- marqueurs `( )`, `(x)`, `(d)`, `(c)` pour les listes de tâches durables ; +- ROADMAP conservant reports et annulations ; +- CHANGELOG synthétique à partir des RC et releases stables ; +- deltas immuables sur le fond ; +- manifests `*.delete.txt` documentés ; +- incrément obligatoire des versions d'en-tête lors de modifications réelles ; +- matrice évolutive de commandes/validations ; +- politique de nettoyage Cargo périodique ; +- règles de modification en RC ; +- génération du prompt suivant après première RC réellement gelée ; +- réservation macOS/iOS sans engagement d'implémentation ; +- Cargo comme version produit canonique des applications Tauri lorsque l'outil le permet. + +## Suite + +`0.2.0-0-pre.2` ouvre l'étude fonctionnelle et le découpage par kernel, capabilities, game-systems, plateformes, providers, services et logique propre aux jeux.