games/docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md

<!-- file: docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md -->
<!-- version: 3 -->

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

### Game AI / bot control

Besoins identifiés :

- adversaire piloté par règles déterministes ;
- bot local embarqué ;
- bot serveur pour parties online ;
- difficulté configurable ;
- décision basée sur un état de jeu réduit ou complet ;
- budget de calcul/tick ;
- reproductibilité éventuelle par seed ;
- remplacement d'un joueur déconnecté dans certains jeux ;
- simulation de charge ou de joueurs synthétiques pour tests.

Le terme « IA » ne signifie pas nécessairement machine learning. Un bot peut être une simple machine à états, un arbre de décision, du pathfinding, une recherche minimax/MCTS ou une stratégie spécialisée.

Le modèle doit permettre d'exécuter la logique côté client ou côté serveur selon le jeu sans dupliquer les règles métier.

### 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

### Portail Web / sites de jeux

Besoins identifiés :

- portail global `games.sasedev.com` ;
- pages/catalogue des jeux ;
- profil joueur global ;
- pages de leaderboard ;
- pages d'aide/support ;
- pages légales et confidentialité ;
- landing pages spécifiques par jeu ;
- possibilité qu'un jeu migre ensuite vers son propre domaine ;
- conservation de l'identité centrale malgré la séparation du site ;
- APIs partagées et APIs spécifiques par jeu ;
- séparation possible entre `www`, `auth`, `api`, `cdn`, `leaderboard`, `realtime`, `admin` et services propres au jeu.

Le découpage DNS/deployment ne doit pas imposer le découpage interne initial. Une architecture modulaire peut commencer déployée ensemble puis être séparée.

### Services Web non temps réel

Besoins identifiés :

- auth/identity ;
- profile ;
- save/progression cloud ;
- leaderboard ;
- inventory/economy authoritative lorsqu'une valeur partagée existe ;
- configuration/rulesets distants ;
- asset metadata/CDN orchestration ;
- administration/modération selon besoins ;
- anti-cheat/validation de résultats ;
- reward authority pour tout jeu avec valeur monétaire ou crypto.

Ces services peuvent être exposés en HTTP(S) et ne doivent pas être placés dans la boucle temps réel uniquement parce qu'un jeu possède aussi un mode multijoueur.

### Lobby / matchmaking / session control

Besoins identifiés :

- création et découverte de partie ;
- invitation/join/leave ;
- matchmaking ;
- allocation d'une room/session ;
- roster de joueurs ;
- ready/start/end ;
- reprise de session ;
- spectator policy éventuelle ;
- routing vers l'instance realtime responsable.

Le control plane d'une partie peut être séparé du data plane temps réel.

### Realtime multiplayer server

Capacités à étudier explicitement :

- endpoint/gateway WebSocket ou transport realtime équivalent ;
- authentification et attachement d'une connexion à une session ;
- ingestion d'inputs/commands client plutôt que confiance dans un état client arbitraire ;
- tick ou cadence serveur ;
- simulation/état authoritative lorsque le jeu l'exige ;
- ordre des messages, sequence numbers et déduplication ;
- acknowledgement lorsque nécessaire ;
- snapshots complets ;
- deltas/patches entre snapshots ;
- version/revision de l'état ;
- interest management pour ne diffuser qu'un sous-ensemble pertinent du monde ;
- broadcast/multicast par room ;
- backpressure et limites de file ;
- détection de timeout/heartbeat ;
- disconnect/reconnect ;
- reprise et resynchronisation après trou de messages ;
- late join ;
- spectator éventuel ;
- historique court/replay buffer lorsque nécessaire ;
- validation anti-cheat des inputs/actions ;
- séparation entre données persistantes et état éphémère de session ;
- métriques, logs, traces et health du service temps réel ;
- horizontal scaling, room placement et transfert/rehydration éventuel d'une session.

### Synchronisation client associée

Les capacités client correspondantes peuvent inclure :

- buffer d'inputs ;
- interpolation ;
- extrapolation limitée ;
- client-side prediction ;
- reconciliation ;
- rollback pour les genres qui le justifient ;
- clock/tick synchronization ;
- snapshot application ;
- delta application ;
- reconnect/resync state machine.

Toutes ne sont pas nécessaires pour tous les jeux. Par exemple Snake à faible fréquence, racing et fighting n'ont pas les mêmes exigences de latence ni la même stratégie de synchronisation.

### Chat et présence

À séparer du gameplay realtime :

- présence online/offline ;
- chat lobby ;
- chat de partie ;
- modération ;
- rate limiting ;
- historique selon produit.

Le déploiement peut commencer comme modular monolith, mais les responsabilités doivent rester séparables afin que le service realtime puisse évoluer indépendamment du Web/API classique.

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