games/docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md

É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 :

game-specific
    ↓
game-systems
    ↓
technical capability APIs
    ↓
engine kernel contracts

Les implémentations sont injectées/composées par le produit :

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 :

game-snake-android
  ├─ game-snake
  ├─ engine-v1-...
  ├─ input-touch adapter
  ├─ render-sdl adapter
  ├─ logging-android
  └─ ads-admob provider [si activé]

Un autre produit :

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 :

[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 :

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.