sanctuary-beta/docs/dynamic-lights-beta030.md

LIGHT-01 — éclairage dynamique, beta.030

Contrat

Les objets lumineux tenus en main principale ou secondaire, les cosmétiques de tête et les objets jetés éclairent le décor et les entités. Les autres joueurs sont des sources au même titre que soi. Un gâteau coiffé d'une bougie n'éclaire que si sa bougie est allumée ; les états des blocs font autorité.

L'effet est visuel côté client, sans bloc artificiel, modification de sauvegarde ou changement des règles de spawn. La lumière utilise la teinte native de la lightmap ; ce ticket ne crée pas de lumière colorée ni d'ombres dynamiques.

Les objets jetés dans une cellule de 4 × 4 × 4 blocs partagent une source : l'objet le plus lumineux la représente, à une position arrondie au demi-bloc. Les quantités des piles ne multiplient pas la lumière. Les sources immobiles ne provoquent pas de reconstructions répétées du terrain. Les calculs utilisent un instantané immuable indexé par section et une file de sections dédupliquée, traitée avec un budget par tick, sans chargement de chunks.

Utilisation et réglages

L'effet est activé de base, sans aptitude. Il suit aussi les objets lumineux tenus par les créatures, leurs équipements de tête et les entités en feu. Les inventaires fermés, coffres et rangées non sélectionnées ne sont pas des sources. Les spectateurs n'éclairent pas les autres joueurs.

config/sanctuary-dynamic-lights.json est créé localement au premier lancement. Le redémarrage du client applique les changements :

Réglage	Valeur initiale	Rôle
enabled	true	Active l'éclairage visuel
updateIntervalTicks	4	Collecte des objets cinq fois par seconde à 20 TPS client
dropClusterSize	4	Taille des cellules de regroupement des objets jetés
maxSources	32	Sources les plus proches ; celle du joueur local est prioritaire
range	48	Distance maximale de collecte autour de la caméra, en blocs
sectionUpdatesPerTick	12	Maximum de sections marquées à mettre à jour par tick
itemOverrides	{}	Intensité 0–15 par identifiant d'objet, par exemple "mod:lampe": 12

Les réglages numériques sont bornés pour éviter un coût accidentel démesuré. Contrôles → Sanctuary propose également « Activer / désactiver les lumières dynamiques », sans touche attribuée par défaut. Ce raccourci agit pour la session. Une désactivation éteint aussi les sections précédemment éclairées.

Les objets-blocs utilisent leur émission native et leur composant BLOCK_STATE. Les bougies colorées et les gâteaux composites utilisent exactement l'état synchronisé du cosmétique. Hors blocs, le seau de lave émet 15, bâton/poudre de Blaze 10, poudre lumineuse/baies lumineuses 8, poche d'encre luisante/cadre luminescent 6. Une surcharge d'objet remplace explicitement ce comportement, y compris son état allumé/éteint ; 0 permet d'exclure un objet.

Portée technique

Le rendu natif de Minecraft 26.3-pre-2 reçoit des coordonnées de lightmap enrichies : terrain et occlusion ambiante, eau, particules, blocs-entités et entités. La lumière du ciel et les surfaces déjà lumineuses sont préservées. Les tâches de reconstruction reçoivent chacune un instantané immuable. Les changements de monde et déconnexions abandonnent les sources précédentes.

La décroissance est radiale, avec la lightmap habituelle de Minecraft : elle ne calcule pas d'occultation par les murs ni de couleur propre à chaque lampe. Les sources distantes au-delà du rayon ou du budget sont ignorées ; beaucoup de sources mobiles peuvent rendre leur suivi plus progressif. Un mouvement de caméra seul ne change pas la position d'une lampe portée.

Vérifications

• Contrôles CPU : 10 000 objets dans une même cellule donnent une seule source, plafonnement des sources, priorité locale, coordonnées négatives, sections dédupliquées, budget strict, aucune invalidation après 500 mises à jour immobiles, déplacement, suppression et conservation des instantanés des workers.

• 100 000 requêtes d'éclairage comparées à une référence brute sans index : mêmes résultats. Sur ce Mac M1, un million de requêtes sur l'index de stress prennent 20–26 ms sur les exécutions de vérification ; c'est une mesure CPU isolée, pas un résultat FPS.

• Client natif réussi (build/dynamic030-client-final.log) : pièce fermée sombre, torche principale, lanterne des âmes secondaire, bloc lumineux sur la tête, gâteau allumé puis éteint, autre joueur avec lanterne, déplacement du porteur et suppression des objets. Les coordonnées de lumière du moteur de monde restent à zéro alors que le maillage et les entités s'éclairent.

• 200 torches jetées fusionnent naturellement en quatre piles, toutes servies par une seule source. Le courant déplace les objets ; l'éclairage les suit. Après leur retrait, l'image redevient sombre. Neuf captures sont conservées dans build/dynamic030-evidence/.

• ./gradlew check build assemblePack -PsanctuaryFocusedTests=lights,cosmetics,familiarhit -PsanctuaryExpansionReload=true réussit : 21 tests serveur, dont le registre complet des objets-blocs, les états de bougies, le gâteau manipulé par un habitant et sa synchronisation. Les régressions des cosmétiques et réactions des familiers passent également. Log : build/dynamic030-check.log.

• Le client natif est lancé avec ./gradlew :sanctuary:runClientGameTest -PsanctuaryClientTests=true -PsanctuaryLightsClientTests=true -PsanctuaryFocusedTests=lights. Le dernier parcours complet réussit.

Livraison locale

Sanctuary-beta.030.mrpack, 4 792 058 octets. Version interne beta.030. Les 1 269 classes compilées correspondent au JAR embarqué ; aucune classe de test n'est distribuée. Le JAR JEI et les classes Demeure sont identiques à beta.029. Les classes existantes de Sanctuary restent identiques, hors l'initialiseur qui enregistre l'éclairage. L'archive beta.029 est préservée.

SHA-256 : 7942c661cbb01b5d0e4b6a59d9839e450223ab57aa3d45297c6816e884d70e80. Reçu : build/dynamic030-artifact.json. Export local vérifié, sans publication du canal ni installation dans Prism.