ADR 0011 : Entrées du joueur captées par l'adaptateur, traduction en actions dans l'adaptateur

Statut : Acceptée
Date : 2026-11-07
Décideur : Ange-Marie MAURIN - A2M Systèmes
Références : docs/SEQUA_Engine_resume_complet_v2.md §4.2, §5.3, §7.0, §7.0.1, §7.2, §10.1, §14, §15 (décisions 1, 3, 6) ; ADR 0007, ADR 0008, ADR 0009 ; spécification docs/specs/protocole-core-rendu-0.1.md (version 0.2 du protocole)

Contexte

Le Core sait recevoir des entrées (session/input, protocole Studio - Core 0.2), les applique au tick suivant et les enregistre : le rejeu est exact (§5.3). Mais aucune touche n'y est reliée, à part dans les tests. Pour éprouver la simulation dans la fenêtre du moteur (et bientôt la voie générative lente, étape 4 bis), il faut que le joueur puisse agir depuis la fenêtre où il regarde le jeu. L'ADR 0009 laisse ce chemin ouvert.

Contraintes :

le moteur ne fait qu'afficher : il ne doit pas déplacer lui-même les objets, sinon ces mouvements échappent à l'enregistrement (décisions 1 et 3) ;
SEQUA 3D est la seule porte vers le moteur, et rien n'y reprend un concept propre à un moteur (§7.0.1) ;
l'auteur doit pouvoir écrire sa propre correspondance avancée (manette, combinaisons, double appui, zones mortes) sans recompiler SEQUA ;
la simulation ne reçoit que des valeurs entières (§10.1).

Options envisagées

Où traduire les touches en actions

Dans le Core : le moteur envoie les touches brutes (codes de touches, axes de manette), le Core les traduit. Une seule table pour tous les moteurs, mais il faut définir un vocabulaire universel de touches et d'appareils, et l'auteur ne peut pas réutiliser les outils de son moteur.
Dans l'adaptateur : l'adaptateur traduit les appareils en actions SEQUA (boutons et axes quantifiés) et ne transmet que ces actions. Chaque moteur offre déjà un système de correspondance (InputMap dans Godot, Enhanced Input dans Unreal), que l'auteur sait utiliser. Ce qui part vers le Core est le même pour tous les moteurs.

Ce qui est enregistré

Dans les deux cas, le Core enregistre ce qu'il reçoit au tick où il l'applique. Avec l'option 2, ce sont les actions : le rejeu ne dépend pas de la correspondance, qui peut changer sans invalider les enregistrements.

Décision

Option 2 : l'adaptateur capte les appareils et les traduit en actions ; le Core ne reçoit et n'enregistre que des actions.

Contrat SEQUA 3D : type three_d::PlayerInput { buttons: uint32, move_x: int16, move_y: int16 } (axes dans [-32767, 32767], même forme que sim::InputFrame), méthode I3DEngineAdapter::poll_input() appelée après chaque image, capacité EngineCapabilities::player_input. La signification des bits appartient au mode de jeu du Core (aujourd'hui sim::button::jump, bit 0). Version d'interface des adaptateurs : 2.
Protocole Core - rendu 0.2 : message render/input du rendu vers le Core, envoyé seulement quand les actions changent. Le Core l'applique comme session/input (prochain tick exécuté, entrée maintenue, la dernière reçue gagne, quelle que soit sa source). À la déconnexion du rendu, une entrée encore maintenue par lui est remise au neutre (pas de joueur qui court tout seul après un plantage).
Focus : un adaptateur ne capte que lorsque sa fenêtre a le focus ; sans focus, il renvoie l'entrée neutre.
Adaptateur Godot, deux niveaux de correspondance :
1. Par défaut : actions de l'InputMap du projet Godot (project.godot, section [input]), modifiables dans l'éditeur Godot ou à la main : sequa_move_left, sequa_move_right, sequa_move_down, sequa_move_up (axes, zones mortes de Godot), sequa_jump (bit 0) et sequa_button_1 à sequa_button_31 (bits suivants, facultatifs). Le projet fourni les relie au clavier (flèches, ZQSD en position physique, espace) et à la manette.
2. Avancé : si la scène principale contient un nœud SequaInput doté d'une méthode sequa_player_input(), l'adaptateur l'appelle à chaque image à la place du niveau 1. Elle renvoie { "buttons": int, "move_x": float, "move_y": float } (axes dans [-1, 1]) ; l'auteur y écrit ce qu'il veut en GDScript (combinaisons, double appui, appareils particuliers). Un résultat invalide donne l'entrée neutre et un message dans le journal du rendu. Un autre projet Godot se désigne déjà par --adapter-options {"project": ...}.
Ce script ne produit que des actions : il ne touche pas aux objets de la scène SEQUA (synchronisation à sens unique, §7.0).
Adaptateur de débogage : entrées scriptées par numéro d'image (--adapter-options {"input": [...]}), pour tester le chemin complet sans moteur ni clavier.

Conséquences

Positives

On joue dans la fenêtre du jeu ; Studio n'a pas besoin du focus.
L'auteur règle sa correspondance avec les outils de son moteur, et peut aller jusqu'au script, sans recompiler SEQUA.
Le Core reste indépendant du moteur et des appareils ; les enregistrements restent valables si la correspondance change.
Unreal se branchera de la même façon (Enhanced Input traduit en PlayerInput).

Négatives et coûts

Chaque adaptateur réécrit sa traduction ; une correspondance écrite pour Godot ne sert pas telle quelle à Unreal.
La correspondance n'est pas enregistrée : on rejoue les actions, pas les touches. Pour analyser le ressenti d'un appareil (§4.2), il faudra un enregistrement à part des entrées brutes.
Un script de correspondance mal écrit peut ralentir l'image : il tourne dans la boucle du moteur.
Deux sources d'entrées (Studio et rendu) se partagent l'entrée maintenue : la dernière gagne, sans arbitrage.
Changement d'interface des adaptateurs (version 2) et du protocole Core - rendu (0.2) : rendu, Core et adaptateurs doivent être reconstruits ensemble (c'est déjà le cas avec le build unifié, ADR 0010).

Questions ouvertes

Latence entre la touche et l'affichage (§14) : render/input porte l'instant de capture ; la mesure de bout en bout viendra avec la lecture des tampons (étape 5).
Plusieurs joueurs et plusieurs appareils : un seul joueur pour l'instant.
Arbitrage entre Studio et le rendu quand les deux envoient des entrées : à décider si cela gêne.
Souris et visée (axes relatifs) : à ajouter quand un mode de jeu en aura besoin.

6.3 KiB Raw Permalink Blame History