Ransom-s-wake/docs/adr/0009-player-knowledge-driven-progression.md

0009 — Progression pilotée par les connaissances et actions du joueur

• Statut : accepté
• Date : 2026-08-10
• Remplace : aucun

Contexte

L'entreprise qui engage le joueur sait qu'elle poursuit un trésor, mais présente la première mission comme la récupération du travail du précédent opérateur. Le monde possède donc une vérité, le commanditaire possède des intentions et le joueur ne dispose au départ que d'une version partielle ou mensongère.

Une épave peut être localisée, identifiée, examinée, ouverte et revisitée sans que son objectif principal ait été sécurisé. Débloquer la suite dès la découverte du navire rendrait la récupération de l'objet ou de l'indice facultative et contredirait la boucle de campagne. À l'inverse, utiliser les secrets du contenu pour colorer une icône ou construire un objectif visible révélerait indirectement une information que le joueur n'a pas encore obtenue.

Décision

Trois niveaux d'information

Le modèle sépare explicitement :

1. La vérité du contenu : identité réelle d'une épave, objets présents, chronologie, motivations et liens narratifs. Elle réside dans les définitions de contenu et n'est jamais envoyée telle quelle à la présentation.
2. Les termes visibles du contrat : ContractTerms contient uniquement le commanditaire affiché, les informations communiquées au joueur, l'objectif officiel, le paiement et les prérequis annoncés.
3. Les connaissances du joueur : MissionProgress contient uniquement les faits observés, révélations acquises, objectifs connus, épaves localisées, identités établies et activités découvertes.

Les intentions cachées de l'entreprise et les véritables étapes de progression sont décrites dans des CampaignObjectiveDefinition distinctes de ContractTerms. Une définition peut rester invisible, devenir connue après une révélation ou n'exister que comme règle interne reliant des faits.

La sauvegarde persiste les identifiants et états nécessaires à la progression, mais l'application expose à chaque écran une projection filtrée par les connaissances du joueur. Le fait qu'une donnée existe dans le contenu ou le format de sauvegarde ne l'autorise pas à traverser le contrat de présentation.

Faits, objectifs et révélations

Un fait est un événement métier idempotent déjà établi, par exemple :

• une zone d'écho a été obtenue ;
• une épave a été localisée ;
• une preuve a été observée ;
• une identité a été établie ;
• un accès a été ouvert ;
• un objet se trouve sur le site, dans le panier, dans la cale ou a été remis ;
• des données récupérées ont été analysées.

Une révélation est une nouvelle connaissance produite par une commande validée et ses prérequis, pas un texte déclenché par l'interface. Elle peut rendre visible un objectif, une activité, une identité ou une nouvelle zone probable.

Un CampaignObjectiveDefinition exprime des prérequis typés et un effet. La progression les évalue après les commandes applicatives. Elle ne dépend ni de la scène ouverte, ni d'un libellé, ni d'une comparaison effectuée dans le HUD. Les mêmes faits ne produisent une révélation qu'une seule fois.

Une hypothèse de joueur, telle que la cible présumée dans le dossier, reste révisable et n'est pas un fait d'identification. Elle ne valide ni le contrat, ni une étape cachée.

Localisation distincte de l'accomplissement

Localiser ou identifier une épave ne satisfait pas automatiquement l'objectif qui y conduit. Chaque étape requiert le dernier fait métier prévu par sa définition : récupération, sécurisation dans la cale, analyse, lecture, remise ou autre action explicitement nommée.

Pour la première mission de la verticale :

1. le contrat visible demande de retrouver le navire de prospection et son module de cartographie ;
2. la localisation rend l'épave revisitable, sans révéler la piste suivante ;
3. l'identification confirme le navire, sans terminer la mission ;
4. les objets placés dans le panier restent provisoires ;
5. le treuillage puis EmptyBasket sécurisent le module et ses données dans la cale ;
6. AnalyzeRecoveredData révèle la zone probable du U-Boot ;
7. la remise physique du module et le paiement restent des actions séparées.

La copie analysable des données demeure acquise après son transfert, même si le module physique est remis ensuite. Les intentions réelles de l'entreprise ne deviennent visibles que par une révélation narrative prévue, pas par le simple accomplissement technique d'un objectif caché.

Projection de la carte

La carte globale reçoit une projection de MissionProgress et applique les états suivants :

• une vérité de contenu non localisée n'est pas affichée comme épave ;
• une zone d'écho connue reste une zone approximative ;
• une épave localisée sans identité établie est nommée Épave non identifiée ;
• une épave identifiée utilise le nom du navire ;
• l'icône est colorée lorsqu'au moins une activité connue et réalisable reste à accomplir ;
• l'icône devient monochrome lorsque toutes les activités connues sont terminées et qu'aucun objectif connu n'y demande une action.

Une activité cachée ne colore pas l'icône : cela divulguerait son existence. Lorsqu'une révélation la rend connue, la projection peut redevenir colorée. Cette couleur est une information de présentation dérivée d'un état métier filtré ; elle n'est pas sauvegardée comme vérité indépendante.

Responsabilités

Le domaine possède faits, prérequis, états d'objets et transitions de progression. L'application exécute les commandes, publie les révélations et construit les projections autorisées. Le monde produit uniquement des observations et interactions. La présentation affiche les projections et émet des commandes ; elle ne lit jamais directement les définitions cachées.

Les tests de contenu vérifient au minimum :

• que le contrat visible ne référence pas une révélation prématurée ;
• que chaque objectif de campagne possède une suite de prérequis atteignable ;
• que la campagne reste terminable sans le pack d'archives facultatif ;
• que localiser ou identifier seul la première épave ne révèle pas le U-Boot ;
• que l'analyse des données sécurisées le révèle une seule fois ;
• que chaque leurre possède des faits cohérents et une contradiction découvrable ;
• qu'aucune projection ne contient un fait ou une activité encore caché.

Conséquences

• L'entreprise peut mentir sans dupliquer une seconde mission ou risquer que l'interface expose son véritable objectif.
• Une épave découverte reste facile à retrouver, mais sa découverte ne court- circuite pas la récupération et l'analyse.
• La carte peut revenir sur une épave lorsqu'une nouvelle activité y est révélée, sans modifier son historique d'exploration.
• Ajouter une révélation exige des prérequis typés et un test de contenu, ce qui augmente le travail d'auteur mais réduit les blocages narratifs.
• Les écrans reçoivent des projections dédiées plutôt que les ressources de contenu complètes.
• Les états de couleur et les libellés de carte restent dérivés et ne créent pas une source de vérité concurrente.

Alternatives considérées

• Mettre objectifs visibles et cachés dans ContractTerms : rejeté, car un écran ou un export de contrat pourrait révéler les intentions de l'entreprise.
• Utiliser des booléens globaux sans propriétaire : rejeté, car leur origine, leur ordre et leurs prérequis seraient implicites.
• Débloquer la suite à l'identification de l'épave : rejeté, car l'objet ou l'indice demandé deviendrait facultatif.
• Laisser l'UI déduire l'objectif suivant : rejeté, car la présentation calculerait une règle de campagne.
• Colorer une épave tant qu'elle contient un secret quelconque : rejeté, car la carte divulguerait les activités inconnues du joueur.
• Valider immédiatement la cible présumée : rejeté, car l'hypothèse doit rester révisable et la déduction ne doit pas devenir un quiz d'interface.