games/docs/studies/020-UROBURAS_CRATE_DECOMPOSITION_STUDY.md

Uroburas — étude de décomposition en crates

Statut

Étude non normative pour 0.2.0-0-pre.6.

Les noms ci-dessous sont des candidats, pas encore des crates à créer immédiatement.

Engine existant

À conserver comme fondation :

crates/engines/engine-v1-common
crates/engines/engine-v1-platform-api
crates/engines/engine-v1-sdl

Le kernel ne doit pas absorber les systèmes de grille, score ou Snake uniquement parce que Uroburas en a besoin.

Capabilities candidates

Famille possible :

crates/capabilities/
    game-assets-lib
    game-input-lib
    game-localization-lib
    game-network-client-lib
    game-persistence-lib
    game-audio-lib

Les noms finaux devront respecter les règles workspace et éviter les crates artificiellement petites.

Game-systems candidates

Famille possible :

crates/game-systems/
    game-grid-lib
    game-collision-grid-lib
    game-stage-lib
    game-score-lib
    game-lives-lib
    game-timed-entity-lib
    game-pickup-lib

Ces crates ne sont créées que si leur API est suffisamment stable et réutilisable.

Des mécanismes très liés peuvent rester regroupés dans une même crate plutôt que multiplier les packages.

Uroburas game crates

Proposition progressive :

crates/games/
    game-uroburas-lib

Cette crate compose les règles Uroburas.

Si la complexité le justifie plus tard :

game-uroburas-core-lib
game-uroburas-content-lib
game-uroburas-protocol-lib

Mais ne pas splitter avant besoin réel.

game-uroburas-lib ne doit pas dépendre directement de :

• Actix ;
• Maud ;
• Lettre ;
• tokio-tungstenite ;
• SDK publicitaire ;
• Java Android ;
• Tauri API.

Applications client

Candidats futurs :

crates/apps/
    game-uroburas-desktop
    game-uroburas-wasm
    game-uroburas-tauri
    game-uroburas-android-entrypoint

Les apps composent :

• jeu ;
• adapters plateforme ;
• capabilities ;
• providers nécessaires.

Server crates

Famille proposée :

crates/servers/
    uroburas-server-domain-lib
    uroburas-server-api-lib
    uroburas-server-web
    uroburas-server-realtime

Puis seulement si besoin :

uroburas-server-media
uroburas-server-admin

server-domain-lib

Contient des concepts serveur partagés :

• PlayerId ;
• MapId/MapVersion ;
• ScoreSubmission ;
• HallOfFameEntry ;
• RewardGrant ;
• Session identifiers.

Ne contient pas Actix/Tungstenite/Tonic.

server-api-lib

Contrats DTO/protocole :

• HTTP DTOs ;
• WebSocket messages ;
• versioning ;
• validation structurale.

Les wire types restent distincts des modèles métier internes.

server-web

• Actix Web ;
• Maud ;
• auth endpoints ;
• Hall of Fame ;
• maps/assets metadata ;
• administration initiale ;
• Fluent serveur ;
• Lettre.

server-realtime

Future Mode 3/2 :

• Tokio ;
• tokio-tungstenite ;
• rooms/worlds ;
• authoritative simulation ;
• snapshots/deltas ;
• spectator ;
• bots.

Providers

Famille possible :

crates/providers/
    game-ads-api-lib
    game-ads-<provider>-lib
    game-auth-<provider>-lib

Ne pas créer les providers tant qu'ils ne sont pas nécessaires à une cible réelle.

Tooling

Candidats futurs :

crates/tools/
    uroburas-map-editor
    uroburas-skin-editor

Un éditeur Web peut aussi avoir sa propre app/host au lieu d'être une crate de jeu.

Anti-monolithe

Avant d'ajouter une fonctionnalité à game-uroburas-lib, poser trois questions :

1. connaît-elle explicitement les règles Uroburas ?
2. serait-elle utile dans un autre jeu sans référence à Uroburas ?
3. dépend-elle d'une plateforme, d'un transport ou d'un provider ?

Si la réponse à 1 est non et à 2 ou 3 est oui, elle appartient probablement ailleurs.