games/docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md

<!-- 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.