sanctuary-beta/docs/backrooms-implementation.md

# BR-01 — Explorer les Backrooms alimentées par le ballast

**Ticket local préparé le 15 septembre 2026. Statut : à implémenter après la
livraison et la validation du suivi du ballast.** Cette préparation est
documentaire ; elle n'active aucune dimension ni aucun transfert en jeu.

- Branche documentaire : `codex/backrooms-ticket`.
- Branche prévue pour l'implémentation : `codex/backrooms-generation`.
- Livraison `beta.xxx` : numéro à attribuer au moment de la livraison du code.
- Cible relevée dans `gradle.properties` : Minecraft **26.3-pre-2**, Java 25.
  Vérifier les API et dépendances de la version effectivement ciblée au démarrage.
- Prérequis bloquant : **suivi du ballast livré**, avec contrat de données et
  preuves de reprise. Référence du ticket amont à ajouter lorsqu'il sera créé ;
  aucun ticket dédié à ce suivi n'est identifié dans le backlog à cette date.

## 1. Résultat attendu

Un joueur termine son sommeil dans son lit de l'Overworld et rejoint sa salle
personnelle, un Indoor de protection situé dans les Backrooms communes. Un
tableau cache une porte ouverte donnant sur le réseau. Le joueur explore des
couloirs, salles, bassins et infrastructures, peut rencontrer un autre joueur
ou découvrir sa salle, puis dort dans un lit trouvé sur place pour revenir à
son propre lit d'origine dans l'Overworld.

Les nouvelles régions portent l'empreinte du ballast réellement suivi dans
Sanctuary. Les régions déjà planifiées conservent leur génération ; les lieux
visités, les constructions et les cartes dessinées par les joueurs restent
utiles après changement de période, reconnexion et redémarrage.

## 2. Décisions du créateur à respecter

Ces règles proviennent de la discussion de conception et priment sur les
anciennes intentions d'accès encore ouvertes dans la vision et la cosmologie.

- Les Backrooms sont le dysfonctionnement d'Indoors interconnectés. Le ballast
  du monde y est redirigé et alimente leur croissance procédurale.
- Steve a aménagé un refuge de protection associé au renoncement à poursuivre
  ce chemin. Il a caché le passage avec **un tableau devant une porte ouverte**.
  Ce geste simple ne fait pas de Steve l'ingénieur de toute l'infrastructure.
- Chaque joueur dispose d'une salle stable, liée à son identité et intégrée
  physiquement à la génération des Backrooms. Le lit est son accès personnel.
- Un autre joueur peut découvrir cette salle à pied et y entrer. Son propre lit
  ne lui permet pas de choisir la salle d'autrui comme destination.
- Le sommeil complet déclenche le passage ; il ne fait pas passer la nuit.
- Dans les Backrooms, **n'importe quel lit utilisable permet de revenir à son
  propre lit d'origine dans l'Overworld**. Son propriétaire ou sa proximité
  d'une salle personnelle ne change pas la destination.
- Les Backrooms ne présentent pas de coordonnées aux joueurs. Chacun construit
  sa connaissance des trajets et sa cartographie.
- Couloirs et salles doivent former des lieux explorables avec des ambiances
  dreamcore, poolrooms et des matériaux liés à l'activité des joueurs, dont
  la cobblestone (« cobble »).

Les modalités des sections suivantes sont des **choix proposés pour réaliser
ce premier lot**. Elles ne sont pas des fonctionnalités déjà livrées.

## 3. Condition de démarrage : le ballast doit être exploitable

Le suivi amont doit fournir et documenter :

1. Les opérations qui produisent du ballast, leurs unités, matériaux, quantités,
   dates/périodes et périmètres d'origine. Distinguer événement terminé, tentative
   refusée et données absentes. Un zéro enregistré n'est pas une panne de collecte.
2. Une identité stable des événements ou lots et une reprise sans double compte.
   Une relecture après arrêt ne produit pas un nouvel apport de matière.
3. Des instantanés immuables et versionnés, identifiables par période et révision,
   dont la lecture ne modifie pas le registre économique. Leur archivage doit
   permettre de comprendre l'origine d'un secteur après évolution du suivi.
4. La nature du ballast : matière comptable, empreinte d'une opération, ou les
   deux. Fixer les règles de réservation, de consommation et de récupération
   lorsque des blocs générés représentent une quantité économique extractible.
5. Le traitement des actions réalisées dans les Backrooms. Générer un bloc,
   rejouer un événement ou recycler un matériau ne doit pas alimenter une boucle
   de création non prévue par le contrat amont.
6. Les contrôles de sauvegarde, de restauration et de conservation des données,
   ainsi qu'au moins un parcours réel allant d'une opération au lot enregistré.

Le socle [d'activité datée](blocodex.md#relevés-datés--portée-de-lalpha23)
observe déjà minage, pose, fabrication, ramassage et jet volontaire. Ces agrégats
ne prouvent ni consommation ni perte ; ils ne distinguent actuellement ni
joueur ni dimension. **Ils ne remplacent pas le prérequis ballast.**

BR-01 consomme l'interface du suivi livré. Il ne crée pas les producteurs
économiques futurs et ne reconstitue pas fictivement leurs transactions.
Les données synthétiques servent aux tests, sans devenir l'historique du serveur.

## 4. Sommeil, salle personnelle et retour

### Parcours nominal

| Situation | Comportement attendu |
| --- | --- |
| Sommeil complet dans le lit personnel validé de l'Overworld | Le serveur prépare la destination, mémorise le retour, puis transfère le joueur dans sa salle. |
| Premier voyage | Une seule salle est réservée pour l'identité du joueur ; son arrivée et ses raccords sont prêts avant le transfert. |
| Voyages suivants, y compris après déplacement du lit personnel | Le joueur retrouve la même salle. Le retour est ancré au lit d'origine de ce nouveau voyage. |
| Réveil volontaire avant la fin du sommeil | Aucun transfert, aucune nouvelle salle créée par le simple début de la pose. |
| Sommeil dans un lit des Backrooms | Retour au lit d'origine enregistré pour ce joueur ; aucune modification de l'ancrage vers le lit utilisé sur place. |
| Deux joueurs utilisent successivement le même lit des Backrooms | Chacun revient dans son Overworld à son propre point de retour. |
| Découverte de la salle d'autrui à pied | Entrée possible ; la salle conserve son identité et son lien au propriétaire. |

Proposition d'interaction : une durée de sommeil individuelle de **100 ticks**
(environ cinq secondes à 20 ticks/s), à éprouver en jeu. Elle ne dépend pas du
nombre de joueurs couchés. Permettre le parcours de jour comme de nuit dans les
mondes Sanctuary où la fonction est activée, sans saut d'heure ni de météo.
Les lits des Backrooms doivent fonctionner sans explosion.

Réutiliser la règle du lit personnel unique et vérifier son implémentation au
démarrage : un point de réapparition ne prouve pas à lui seul la propriété d'un
lit. Si cette association manque, la liaison minimale joueur/lit fait partie
du parcours BR-01 ; la politique de remplacement doit préserver les lits déjà
posés. Les lits portés comme accessoires décoratifs ne sont pas des accès.

### Conservation et incidents

- Le lien à la salle repose sur l'identité persistante, jamais sur le pseudo,
  le nom d'un lit, un prestige ou les coordonnées du lit extérieur.
- Enregistrer le retour avant le départ. Un transfert a une identité et un état
  persistants ; interruption, nouvelle requête ou reprise ne créent pas une
  seconde salle et ne dupliquent pas l'inventaire.
- Si la destination n'est pas prête, maintenir le joueur en sécurité à la source
  et permettre d'annuler. Ne pas transférer dans un chunk incomplet.
- Déconnexion avant transfert : annuler le sommeil. Déconnexion après transfert :
  reprendre à la dernière position sûre sauvegardée dans les Backrooms, avec
  le même retour. Un redémarrage n'impose pas un réveil dans l'Overworld.
- Lit d'origine détruit ou arrivée obstruée : proposer un retour à une position
  sûre proche de l'ancrage, recherchée dans un rayon borné ; à défaut, utiliser
  l'arrivée sûre de l'Overworld. Signaler ce secours en FR/EN. Ne pas recréer le
  lit, modifier le terrain ni rediriger vers la salle d'un autre joueur.
- Mort : retour proposé dans l'Overworld selon cet ancrage et ce secours ;
  conserver les règles Sanctuary existantes de mort, d'XP, d'inventaire et de
  tombe. Une tombe éventuelle reste à son emplacement et ne révèle pas ses
  coordonnées dans les interfaces joueur. Aucun système de restitution nouvelle
  des objets perdus n'est ajouté par BR-01.
- Pour le premier lot, la protection de la salle signifie une arrivée sûre et
  l'absence d'apparition naturelle de monstres à l'intérieur. Elle ne crée pas
  implicitement de claim, de verrou de visite ou de règle d'invulnérabilité.
  Les droits existants s'appliquent aux modifications ; les changements permis
  aux joueurs persistent, y compris si le tableau ou la porte est retiré.

## 5. Monde partagé et génération progressive

### Hébergement proposé

Utiliser une dimension technique commune, avec l'identifiant proposé
`sanctuary:backrooms`, à vérifier libre avant enregistrement puis à conserver.
Les salles personnelles sont des emplacements dans ce monde partagé. Les trajets
du premier lot sont physiques, continus et stables ; le lit assure les transferts
vers et depuis l'Overworld.

Un **secteur** est un ensemble de salles et de circulations planifié comme une
unité. Son plan contient les emprises, niveaux, raccords aux secteurs voisins,
réservations de salles personnelles et données de génération.

### Ordre de génération

1. Réserver un secteur libre et ses raccords. Associer un instantané de ballast,
   une graine dérivée, une version de générateur et une version de recettes.
2. Produire le réseau des pièces : couloirs, embranchements, boucles, impasses
   lisibles, différences de hauteur et espaces que l'on aperçoit avant d'y accéder.
3. Attribuer fonctions et ambiances aux ensembles de pièces. Prévoir les
   transitions et les emplacements stables des refuges personnels.
4. Construire sols, enveloppes, plafonds, supports, portes, escaliers et bassins.
   Valider passage à hauteur de joueur, raccords et confinement de l'eau.
5. Appliquer les matériaux par rôle, puis le mobilier, les lumières et les repères.
6. Rendre les portions prêtes accessibles à mesure de l'exploration, en respectant
   un budget borné de travail et de génération anticipée.

Les portes de liaison aux secteurs futurs sont prévues dès le plan initial.
Une nouvelle salle personnelle occupe une réservation libre ou un nouveau
secteur raccordé ; elle n'écrase pas une pièce ni une construction existante.
Le plan garantit un chemin vers le réseau commun et évite les poches isolées.

Les raccords partagés utilisent une convention déterministe conservée côté
serveur, indépendante de l'ordre de chargement des chunks. Deux joueurs qui
approchent par des côtés différents réutilisent la même réservation. Le ballast
ne doit jamais être relu en direct pour changer un raccord pendant sa construction.

La planification réserve une géométrie ; elle ne garde pas tout le monde chargé.
Bornes de secteur, anticipation, tâches par tick et file d'attente seront
configurables. Une file saturée ralentit la préparation et maintient les accès
non prêts fermés de manière sûre. Mesurer les coûts sur le serveur de test.

## 6. Architecture, ambiances et matière

Les plans varient leurs proportions et leurs connexions. Des éléments composés
à la main peuvent fournir portes, éclairages ou mobilier ; ils ne doivent pas
imposer une unique salle répétée à chaque tirage.

| Famille du premier lot | Formes et usages | Repères et transitions |
| --- | --- | --- |
| Habitation | Chambre, dortoir, salon, couloir étroit | Mobilier, changements de hauteur, ouvertures vers d'autres pièces. |
| Poolrooms | Bassins, arches, passerelles, vestiaires, douches | Rigoles et zones humides annoncent les bassins ; un chemin praticable permet de progresser. |
| Infrastructure minérale | Réserves, fondations, soutènements, galeries de maintenance | Cobble, pierre et réparations visibles derrière les enveloppes aménagées. |
| Traitement dreamcore transversal | Jardin enfermé, lumière évoquant le jour, fenêtre intérieure, volume disproportionné | Étrangeté obtenue d'abord par proportions, répétitions et vues ; aucun portail à rendu spécial requis. |

La relation au ballast agit sur les familles de volumes, les proportions de
matériaux et leurs rôles. Exemples de recettes proposées :

- Pierre/cobble : épaissir les fondations et favoriser les galeries techniques.
- Bois travaillé : favoriser cloisons, chambres, réserves et passerelles.
- Verre : favoriser serres, espaces d'observation et séparations transparentes.
- Cuivre : favoriser des équipements et architectures techniques ou hydrauliques.

Conserver des palettes par fonction : une poolroom garde son identité même si
le ballast minéral domine. Les pondérations plafonnées ou à croissance ralentie
évitent que les matériaux les plus abondants effacent toutes les autres familles.
Ces transformations de poids n'altèrent jamais les quantités du registre source.

La relation à l'action n'est utilisée que si le suivi la fournit explicitement :
du cuivre observé ne prouve pas à lui seul qu'une usine a été construite.

### Périodes et ressources

- Associer chaque secteur à une période/révision au moment de sa réservation et
  conserver les données suffisantes pour reproduire ce plan. Le changement de
  période influence uniquement de nouvelles réservations.
- Fournir une base architecturale ancienne pour un serveur au ballast enregistré
  nul. L'identifier comme héritage fictionnel ; ne pas inventer d'activité passée.
- En cas d'indisponibilité du suivi, continuer à charger les secteurs connus et
  les retours sûrs ; suspendre la réservation de nouveaux secteurs. Une panne
  ne doit pas devenir silencieusement une période de ballast nul.
- Distinguer l'influence visuelle de la matière comptable récupérable. Avant de
  rendre des blocs issus du ballast extractibles, appliquer le contrat amont de
  débit/réservation et de reprise, sans double attribution entre secteurs.
  La minabilité et les drops du décor doivent être fixés et testés avant livraison.
  Aucun coffre ne copie automatiquement les objets des joueurs.

## 7. Orientation et intégration au client

- Masquer les positions numériques des surfaces fournies par Sanctuary et du
  client pris en charge dans cette dimension : F3, HUD, Atlas, marqueurs,
  Demeure, fiches de lieux, notifications, tombe et messages de transfert.
- Suspendre le relevé et l'affichage automatiques de la carte/mini-carte pour les
  Backrooms. Préserver les cartes déjà enregistrées pour les autres dimensions.
  Vérifier aussi les fonctions natives de carte qui pourraient contourner ce
  parcours dans le client distribué.
- Préserver les moyens manuels existants : noms, panneaux, livres, croquis et
  repères construits. Un éditeur de carte manuelle est hors de ce ticket.
- Ne pas diffuser un annuaire des salles personnelles ni leurs positions.
  La découverte physique reste possible, sans autorisation du propriétaire.
- Les coordonnées restent utilisables dans des diagnostics opérateur explicites
  et les preuves de test. L'absence de coordonnées est une règle d'interface et
  de jeu, pas une promesse de cacher la position à un client modifié.
- Tous les nouveaux messages et libellés sont fournis en français et en anglais.

## 8. Persistance, migration et version de génération

Avant le code qui écrit des données, documenter les schémas et transitions :

- par joueur : identité, identifiant stable de salle, ancrage de retour et état
  d'un éventuel transfert ;
- par secteur : identifiant/emprise, voisins et raccords, état de préparation,
  graine, versions, instantané de ballast et réservations de refuges ;
- pour la reprise : étapes déjà enregistrées, réservations de matière lorsque
  nécessaires, traitement d'une interruption entre planification et disponibilité.

Conserver les chunks Minecraft comme état construit et modifiable. Le plan
sert à produire les portions neuves ; il ne repeint pas les chunks sauvegardés.
Une donnée invalide est signalée et conservée, sans recréation silencieuse de
salle ou de registre vide. Une mise à jour ne réinterprète pas les secteurs
anciens avec de nouvelles recettes.

Développer d'abord sur des mondes neufs dans les dossiers ignorés. Avant toute
activation sur une sauvegarde existante, livrer un contrat d'adoption explicite :
ajout de la dimension et des registres, initialisation des liaisons aux lits,
conservation de l'Overworld, retour des joueurs présents dans les Backrooms lors
d'une désactivation et limites d'un retour de version. Une désactivation ne
supprime jamais les secteurs ni le ballast. Aucun déploiement personnel n'est
inclus dans la rédaction ou l'implémentation de ce ticket.

## 9. Étapes de réalisation du premier lot

Les étapes composent un seul parcours livrable. Les prototypes intermédiaires
restent dans les mondes de développement jusqu'à satisfaction des critères.

1. **Contrats et intégration** : vérifier la livraison ballast, fixer son
   adaptateur, les schémas, la minabilité du décor et la règle du lit unique.
2. **Aller-retour** : dimension commune, deux salles distinctes, tableau et porte,
   sommeil serveur, persistance et retours ordinaires/de secours.
3. **Réseau procédural** : secteur d'essai d'environ 12 à 20 pièces, au moins
   une boucle et deux altitudes, habitation → poolrooms → infrastructure ;
   une scène dreamcore et des repères reconnaissables. Les nombres sont des
   objectifs de prototype, pas des tailles universelles du monde.
4. **Ballast et extension** : relier les recettes aux instantanés réels, comparer
   plusieurs profils, prolonger vers un autre secteur et éprouver les reprises.
5. **Parcours client et livraison** : orientation manuelle, FR/EN, multijoueur,
   performances, sauvegardes et preuves des critères ci-dessous.

## 10. Critères d'acceptation

Toutes les cases décrivent des vérifications futures ; aucune n'est validée par
la préparation de ce document.

- [ ] **Prérequis** : contrat/version du suivi ballast référencés ; une opération
  réelle alimente un lot puis un nouveau secteur sans transaction inventée.
- [ ] **Accès** : sommeil complet individuel, de jour et de nuit, déclenchant
  exactement un départ ; réveil anticipé sans départ ; temps et météo conservés.
- [ ] **Identité et visite** : A et B ont deux salles persistantes dans le même
  réseau ; A rejoint celle de B à pied et y entre ; chaque lit extérieur mène
  exclusivement à la salle de son joueur.
- [ ] **Retour** : A et B utilisent successivement un même lit des Backrooms,
  dont celui d'une salle tierce, et rentrent chacun à leur origine. Tester lit
  d'origine détruit, obstruction, remplacement et lit des Backrooms retiré
  pendant le sommeil. Aucun transfert ne place le joueur dans le vide ou un mur.
- [ ] **Interruption et mort** : reconnexion, redémarrage et arrêt à chaque étape
  du transfert conservent une salle et un inventaire uniques ; mort/tombe suivent
  le contrat existant et le secours reste praticable.
- [ ] **Géométrie** : sur les graines `0`, `42` et `20260915`, démontrer deux
  refuges raccordés, une boucle, deux altitudes, des passages praticables,
  des bassins contenus et aucun raccord involontaire vers le vide.
- [ ] **Identité des lieux** : parcours client montrant habitation, poolrooms,
  infrastructure en cobble et au moins une scène dreamcore ; repères suffisants
  pour refaire un trajet sans coordonnées. Une validation visuelle accompagne
  les contrôles géométriques.
- [ ] **Empreinte matérielle** : à graine et recettes égales, trois instantanés
  contrôlés pierre/cobble, bois et verre/cuivre produisent des différences
  vérifiables de matériaux/rôles tout en préservant le parcours et les ambiances.
- [ ] **Histoire conservée** : un nouvel apport affecte un nouveau secteur ;
  plan, constructions, contenus et blocs déjà générés du premier restent
  inchangés. Une période nulle et des données manquantes suivent deux traitements
  distincts. Les éventuelles quantités extractibles ne sont attribuées qu'une fois.
- [ ] **Concurrence et reprise** : charger un plan par plusieurs ordres de chunks,
  puis par deux explorateurs simultanés ; obtenir les mêmes raccords. Interrompre
  la création d'un secteur et reprendre sans double réservation ni réécriture
  de portions déjà disponibles aux joueurs.
- [ ] **Orientation** : aucun affichage de coordonnées ni cartographie automatique
  des Backrooms dans les surfaces prises en charge ; cartes de l'Overworld
  conservées, diagnostics opérateur explicites, messages et parcours FR/EN testés.
- [ ] **Charge et adoption** : file de génération bornée, arrivée sûre même en
  retard de préparation, absence de blocage serveur ; fournir budget retenu,
  mesures de temps de génération/tick/mémoire et configuration de la machine.
  Vérifier le contrat d'adoption et le retour avant désactivation sur une copie
  de développement, sans régénérer l'Overworld.

### Vérifications et preuves à produire lors de l'implémentation

- Tests purs du plan : raccords, accessibilité, recettes et reproductibilité.
- GameTests serveur ciblés : sommeil, identité, retours, persistance, fluides,
  ballast et absence de doubles effets. Essais à deux clients pour le parcours
  complet et ses rendus ; un test serveur seul ne valide pas le masquage client.
- `./gradlew check build`, puis `./gradlew assemblePack` si la distribution change.
- Rapports avec version Minecraft/mod/générateur, graines, instantanés de ballast,
  coordonnées opérateur, configuration et captures. Conserver mondes et artefacts
  dans les dossiers de développement ignorés ; résumer les preuves dans le ticket.
- À la livraison du mod, synchroniser `mod_version`, `pack_version` et
  `packwiz/pack.toml` avec le prochain `beta.xxx`, conformément au
  [versionnement](versioning.md). Ce document seul n'incrémente aucun binaire.

## 11. Hors périmètre et décisions de démarrage

Hors lot : système d'affinités/némésis, nouveaux pouvoirs, générateur général
d'Indoors achetables, mailbox, shop, objets perdus restitués, quêtes/boss de
Backrooms, portails à rendu transparent, géométrie qui se reboucle par
téléportation, évolution des pièces déjà construites et éditeur de cartes.

À fixer dans la première étape à partir du suivi livré : référence du prérequis,
unités et périodes du ballast, droits d'extraction/drops, dimensions des secteurs,
budgets de génération et détails de migration. Les réglages proposés de sommeil
et de secours sont à éprouver. Ces décisions ne rouvrent pas les règles d'accès,
de visite et de retour confirmées par le créateur.

## 12. Références

- [ANO-01 — doubles de Steve](steve-anomalies.md) prépare la suite : Herobrine
  dans les Backrooms, mineur fantôme dans l'Overworld et les Backrooms, Steve
  bugué persistant et transportable. Ces anomalies ont leurs lots propres et
  ne bloquent pas la livraison du réseau BR-01. Leurs futures modifications
  de blocs seront des actions de gameplay sauvegardées, jamais une régénération
  implicite des secteurs existants.
- [Cosmologie : matière, espaces et mémoire](cosmologie.md).
- [Vision : dimensions et espaces](vision.md#dimensions-et-espaces).
- [Blocodex : portée des relevés disponibles](blocodex.md).
- [Temps réel : sommeil et horloges](realtime-beta037.md).
- [Règles de contribution](../CONTRIBUTING.md) et
  [modèle Fonctionnalité](../.gitea/ISSUE_TEMPLATE/feature.md).

Le document conceptuel « Système des Habitants, Affinités et Anomalies » a nourri
la discussion ; ses autres mécanismes ne sont pas des dépendances de BR-01.