0.2.0-0-pre.2

docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md

@@ -0,0 +1,377 @@
+<!-- file: docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md -->
+<!-- version: 1 -->
+
+# 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.