sanctuary-beta/docs/realtime-beta037.md

TIME-037 — temps réel et suivi commun

Branche codex/realtime-tracking-beta037, base beta.036. Minecraft 26.3-pre-2 et Java 25. Contrat écrit avant l’implémentation.

Demande retenue

Le suivi des futurs objectifs de quête utilise le même système que les notifications et advancements : même position, mêmes jauges, mêmes règles visuelles et mêmes options. Aucun second HUD en haut à gauche. Les quêtes, panneaux, rubis/saphirs, récompenses et visiteurs ne sont pas créés ici.

Le temps réel est activé par défaut dans les mondes concernés. En solo, le fuseau de la machine est automatique. Le créateur confirme une ville de référence du fuseau, sans IP ni géolocalisation, pour estimer le soleil saisonnier. En multijoueur, le serveur choisit son fuseau et sa région de référence dans sa configuration.

Contrat de migration et de retour

L’activation concerne les mondes Sanctuary et le profil Sanctuary Test. Un monde Minecraft ordinaire garde son horloge native. Aucun monde personnel n’est ouvert par le développement ; essais uniquement dans les dossiers ignorés.

Au premier lancement avec le nouveau mode, un fichier distinct data/sanctuary-realtime.json consigne un ancrage de calendrier et les paramètres natifs de vitesse/pause avant activation. Il est écrit atomiquement avant d’appliquer le nouveau temps. Le jour Minecraft courant est conservé comme base, puis avance d’un jour par jour réel ; l’heure se cale immédiatement sur le soleil réel estimé. Pas d’âge artificiel de plusieurs dizaines de milliers de jours. Un changement de région ou de mode réancre cette base sans simuler les jours manqués.

L’horloge de simulation gameTime, les ticks planifiés, cultures, fours, fluides, croissance des entités, inventaires et progression ne sont ni sautés ni ralentis. Aucun rattrapage de simulation hors ligne. Les comportements naturellement liés au jour/nuit, dont les routines des villageois, suivent en revanche la journée solaire plus longue. Génération, chunks, structures, graines et expansions restent inchangés. Aucun schéma de sauvegarde existant n’est remplacé.

Le fichier d’horloges natif garde une vitesse/pause native lors de l’enregistrement, même pendant le temps réel. Sans le mod, le monde reprend donc son rythme natif à partir de sa dernière heure, sans conserver une vitesse solaire très lente. Le mode vanilla rétablit cette même vitesse/pause, à l’heure courante ; il ne restaure pas un ancien gameTime. Les preuves d’ancrage restent dans le fichier séparé. Un fichier invalide ou modifié extérieurement est refusé sans écrasement.

Soleil et limites visuelles

L’heure et la date viennent de l’horloge du serveur intégré ou dédié. Les jours allongent/raccourcissent selon la latitude de référence et la saison. Le fuseau Java gère les changements d’heure civile ; le soleil est calculé en instants UTC pour rester continu lors du passage été/hiver. Les références publiques IANA sont embarquées ; aucun accès réseau en jeu. Un fuseau sans ville de référence utilise un repère équatorial à son méridien horaire, annoncé comme approximation.

Les levers, midi solaire et couchers cadrent les phases du ciel Minecraft. Les nuages et l’orbite restent natifs : ce n’est pas un moteur astronomique complet. Les journées polaires conservent un ciel de jour et les nuits polaires un ciel de nuit, avec soleil stationnaire dans cette première version.

Le sommeil en lit conserve sa pose et son point de réapparition mais ne saute plus la nuit et ne change pas la météo. Les apparitions naturelles de phantoms liées à l’insomnie sont désactivées en temps réel, conformément à la vision. Les phantoms existants, œufs et familiers ne sont pas supprimés ; les autres fantômes prévus dans la vision restent hors de ce ticket.

Les commandes administrateur permettent de consulter le mode et les heures, de recharger la configuration, et de revenir au temps Minecraft. Les commandes natives qui changent l’horloge solaire doivent signaler que le temps réel la contrôle ; les requêtes de lecture et les autres horloges restent disponibles.

Sources techniques

Formules solaires approximatives de NOAA, références géographiques publiques de IANA tzdb. Les API d’horloges, paquets, timelines et sommeil sont vérifiées dans les sources exactes de Minecraft 26.3-pre-2 fournies par Loom.

Utilisation

En solo, aucune saisie : le fuseau de la JVM suit celui de la machine au lancement. Exemple Europe/Paris : référence publique Paris. Aucun paramètre client ne permet de modifier l’heure d’un serveur dédié.

Sur serveur dédié, modifier config/sanctuary/realtime.json :

{
  "enabled": true,
  "serverTimeZone": "Europe/Paris",
  "solarRegion": "auto"
}

auto prend la ville associée au fuseau. solarRegion accepte aussi un autre identifiant IANA de référence, par exemple Europe/London. Ne pas entrer de coordonnées privées. Par défaut dédié : UTC, repère équatorial approximatif. La liste embarquée est data/sanctuary/realtime/zone-references.json dans le JAR.

• /sanctuary time : mode, date/heure civile, lever et coucher estimés.
• /sanctuary time reload : recharge le fichier de configuration (opérateur).
• /sanctuary time vanilla : reprend le rythme Minecraft dans ce monde (opérateur).
• /sanctuary time realtime : reprend l’heure réelle, si la configuration l’autorise (opérateur).

L’option globale enabled: false arrête le pilotage solaire. Un monde créé pendant cette désactivation nécessite /sanctuary time realtime après réactivation. Une configuration invalide au lancement conserve l’horloge native ; un rechargement invalide laisse la dernière configuration valide en place et signale l’erreur. Les commandes natives /time de modification exigent le mode vanilla ; les lectures restent possibles. Le profil plat utilise aussi le temps réel, avec ce même retour explicite au rythme Minecraft pour les essais.

Contrat du suivi commun

ObjectiveTracker centralise les instantanés par couple source/identifiant. Les advancements natifs sont déjà branchés sur ce moteur. Un futur adaptateur de quêtes transmettra ses instantanés validés par le serveur à NotificationClient.objectives("quest", ...), sur le thread client, puis pourra utiliser toggleObjective pour le choix manuel. Cette API est uniquement une présentation : aucune validation de quête, récompense ou découverte côté client.

Premier instantané silencieux, message seulement quand la progression augmente, barre temporaire expirante, épingle retirée à la réussite, trois épingles communes maximum. Mort/respawn nettoient le fil et les instantanés temporaires ; un nouvel instantané remet les épingles à jour. Déconnexion vide le contexte du serveur. Les préférences beta.036 et leurs identifiants d’advancements restent lisibles, sans migration forcée ; les autres sources utilisent source|identifiant.

Le raccord au rendu traite aussi les retours anticipés de Minecraft lorsque F3 n’a aucune ligne ; le suivi apparaît donc pendant le jeu normal.

Même position, options, textures natives et évitement F3/boss/hotbar pour toutes les sources. Aucun panneau de quête ni nouvelle quête n’est ajouté dans le jeu.

Validation

Livré localement en beta.037. ./gradlew check build assemblePack assembleTestPack réussit avec 29 tests serveur ciblant temps réel, notifications, progression, mouvements, collections et recettes. Les 7 765 assertions du test solaire et du suivi couvrent les fuseaux Java disponibles sur les douze mois de 2026, les solstices nord/sud, jours polaires, année bissextile, DST, ligne de date, continuité à minuit, configurations, contrat atomique et objectifs mixtes.

Le test serveur vérifie les paramètres natifs sauvegardés, le paquet de synchronisation, le temps de simulation inchangé, les permissions, le refus des commandes /time en temps réel, l’End indépendant, les phantoms naturels et les retours/rechargements de configuration sans perdre les modifications administrateur effectuées en mode vanilla.

Deux parcours client natifs réussissent sur des mondes plats de développement :

• lever, midi et coucher aux angles natifs attendus, synchronisation réelle du paquet d’horloge, entrée dans un lit et sommeil profond sans saut de nuit ;
• source de quête synthétique uniquement dans les tests : rendu sans F3, expiration, épingle et retrait à la réussite ;
• régression du suivi par clic/re-clic/glissement dans Advancements, conservation après respawn, 36 dispositions avec F3 et son échelle indépendante, boss, hotbar, écrans FR/EN, descente réelle avec un perroquet porté.

Les captures ont été inspectées dans build/realtime037-evidence/. Logs : build/realtime037-check-final.log, build/realtime037-client-release.log, build/realtime037-regression-client.log. Reçu d’artefact : build/realtime037-artifact.json.

Les 1 353 classes du mod et les trois classes de l’extension de test correspondent au build. Génération, ressources préexistantes hors langues/notices, code Demeure et JAR JEI sont inchangés. Les deux beta.036 gardent leurs empreintes initiales. Ni canal public, ni installation Prism personnelle, ni monde personnel modifié.

La validation ne simule pas plusieurs jours réels d’hébergement continu : les frontières calendaires sont testées avec une horloge déterministe. Le soleil reste une approximation liée à une ville publique ; aux pôles il reste fixe le jour ou la nuit. Les quêtes et leurs récompenses ne sont pas livrées ici.

Artefacts vérifiés

• Sanctuary-beta.037.mrpack — 5,014,547 octets. SHA-256 : e91d29dddf5ee26098a4de6fff85a5cfa5ce920304754c12aecd06cf8b6a9d2d.
• Sanctuary-Test-beta.037.mrpack — 5,033,482 octets. SHA-256 : 9b4e3c60e507e2ab9e3bf666615d833db8b0e4375454dc727aff7f5155c4b043.