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](../build/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.