[Spec] Circuit Racing : entraîner des pilotes et courir contre eux

[salim4n]

Parent

#6

Circuit Racing — spécification validée

Remplace le périmètre initial de #9. Cible produit approuvée : vrais véhicules 3D, entraînement des modèles, compétitions IA et joueur contre IA. Choix de première version et découpage validés par le mainteneur.

Problem Statement

La démo actuelle présente un véhicule fait de primitives sur un ovale à vitesse constante. Elle ne propose ni conduite jouable, ni choix de pilotes sauvegardés, ni course simultanée. Le visiteur ne peut pas affronter les modèles entraînés.

Solution

Une expérience de course locale dans le navigateur avec trois modes : Entraîner, Course IA et Jouer contre les IA. Un garage sépare apparence du véhicule et pilote appris. La scène de course occupe l'espace principal, les réglages d'apprentissage sont accessibles dans leur mode dédié.

User Stories

1. Comme joueur, je veux choisir un véhicule 3D identifiable dans un garage.
2. Comme joueur, je veux accélérer, freiner et diriger la voiture au clavier.
3. Comme joueur, je veux une caméra de poursuite stable et un retour clair sur ma vitesse.
4. Comme joueur, je veux un circuit comportant lignes droites, virages variés et limites visibles.
5. Comme joueur, je veux comprendre les commandes avant le départ.
6. Comme joueur, je veux voir le compte à rebours, ma position et mes tours.
7. Comme joueur, je veux que collisions, sorties de piste et remise en piste aient des règles explicites.
8. Comme utilisateur, je veux entraîner un pilote dans ce même environnement de conduite.
9. Comme utilisateur, je veux arrêter, reprendre ou recommencer un entraînement sans confusion.
10. Comme utilisateur, je veux sauvegarder un pilote et le retrouver après rechargement.
11. Comme utilisateur, je veux connaître la provenance et les résultats du checkpoint choisi.
12. Comme utilisateur, je veux tester mon pilote sur un circuit réservé au test.
13. Comme spectateur, je veux sélectionner plusieurs pilotes pour une course simultanée.
14. Comme spectateur, je veux choisir la voiture suivie par la caméra.
15. Comme joueur, je veux affronter les pilotes réellement entraînés.
16. Comme joueur, je veux consulter les résultats puis relancer la course.
17. Comme utilisateur, je veux un message explicite si un modèle est absent ou incompatible.
18. Comme développeur, je veux que les mêmes règles physiques s'appliquent aux joueurs et aux IA.

Implementation Decisions

• Première version : navigateur desktop, clavier, conduite arcade, jusqu'à quatre voitures (un joueur et trois IA, ou quatre IA). Pas de multijoueur réseau.
• Au moins deux modèles 3D importés avec provenance et licence conservées. Apparences différentes, caractéristiques physiques identiques dans cette version pour permettre une comparaison loyale des pilotes.
• Circuit fermé avec enchaînement de virages, checkpoints ordonnés et ligne de départ. Un deuxième tracé réservé à l'évaluation. Les anciens ovales restent des fixtures du protocole v1.
• Contrat de conduite versionné avec neuf combinaisons discrètes : gauche/neutre/droite × accélérer/rouler/freiner. Joueur et agents utilisent le même contrat. Accélération, freinage, vitesse maximale et direction bornées.
• Une simulation commune à pas fixe fait avancer tous les véhicules. Les politiques observent un même état de départ du tick ; leur ordre d'appel ne doit pas donner un avantage.
• Collisions arcade entre voitures et limites, sorties de piste ralenties et remise en piste après immobilisation prolongée avec pénalité explicite. Ces règles existent aussi pendant l'entraînement ; une erreur récupérable n'est pas automatiquement une terminaison.
• Observations comprenant conduite, anticipation du tracé et proximité des adversaires ; apprentissage solo puis avec trafic de référence figé. Une seule politique apprend par environnement d'entraînement ; les autres restent figées.
• Pilotes sauvegardés localement avec version de contrat, modèle, configuration, provenance et résultats. Refus explicite des checkpoints de l'ancien contrat à vitesse constante.
• Modes course et évaluation chargent des politiques figées séparées de l'instance entraînable. Aucun changement de poids durant une course.
• Décompte des tours par checkpoints parcourus dans l'ordre ; raccourcis et va-et-vient sur la ligne ne comptent pas comme un tour.
• Affichage course : vitesse, position, tour, chronomètre, mini-carte et pause. Affichage entraînement : réussite, incidents, progression et sauvegarde.

Testing Decisions

• Tests de comportement au niveau de la simulation publique : même état et mêmes commandes donnent le même résultat indépendamment du rendu ; effets de freinage, collisions, remise en piste et arrivée.
• Tests de comptage des tours, raccourcis, marche arrière et classement, y compris égalités déterministes.
• Intégration entraînement → sauvegarde → rechargement → évaluation → course, avec absence de mutation des poids en course.
• Mesures sur plusieurs graines et parcours réservés au test. Critères du checkpoint fixés avant sélection ; aucune promesse de compétence avant les résultats.
• Vérification navigateur de chaque tranche jouable : commandes clavier, perte de focus, pause, chargement/erreur d'asset, caméra, résultats, reprise après rechargement.
• Mesurer débit, FPS et temps de frame sur une machine/browser identifiés ; objectif proposé de 60 FPS desktop, à mesurer plutôt qu'à affirmer. Chargement local des assets, taille et temps de chargement consignés.
• La preuve finale exige une course complète du joueur contre au moins un pilote entraîné, avec checkpoint et résultat identifiables. Un contrôleur à règles ne satisfait pas cette preuve.

Out of Scope

Réseau, comptes, matchmaking, simulation automobile réaliste, voitures aux performances différentes, mobile tactile, SAC/actions continues, self-play compétitif complet, déploiement.

Further Notes

#7 et #8 sont des commits locaux ; la validation complète comporte encore deux suites bloquées par le binding TensorFlow natif manquant. Le prototype visuel et jouable du premier ticket permettra d'éprouver la conduite et la caméra avant de produire les checkpoints. #11 et #12 devront utiliser le nouveau contrat de conduite ; leurs dépendances seront mises à jour après validation du découpage.

Blocked by

#8