# Blocodex natif — connaissances, matière et stocks

Ticket META-01, branche `codex/blocodex-natif`, cible Minecraft **26.3-pre-2**.
Le Blocodex appartient au mod Sanctuary. Il est disponible sans appareil,
recette ni déblocage. La mémoire personnelle, le recensement du terrain et
celui des stocks forment un socle commun aux futures palettes de structures,
règles d’expansion et règles du shop. Les relevés datés ajoutent la temporalité
nécessaire à une future lecture de l’histoire économique du serveur.

## Contrat des informations

La mémoire est personnelle : une identité de joueur (UUID), dans une sauvegarde
de serveur, partagée entre ses dimensions. Les indicateurs sont indépendants.

| Information | Sens |
| --- | --- |
| Inconnu | Aucune observation, possession, pose ni statistique de minage ou de jet. C'est un état calculé, pas une étape enregistrée. |
| Vu | Le premier bloc rencontré par le regard du joueur, à au plus 32 blocs, observé côté serveur tous les 5 ticks. Les obstacles arrêtent le rayon ; les chunks absents ne sont pas chargés. Ce relevé ne couvre pas chaque pixel du champ de vision. |
| Miné | Compteur vanilla `mined` du bloc. Ses règles sont conservées : notamment pas de minage créatif, ni de minage sans l'outil requis. |
| Déjà possédé | Le bloc, sous forme d'item, a été présent dans l'inventaire personnel ou sur le curseur d'un menu. Les statistiques vanilla de ramassage et de jet prouvent aussi une possession passée. |
| Jeté | Compteur vanilla `dropped` de l'item du bloc. Il compte les unités volontairement jetées, pas les objets éjectés à la mort ni le butin produit par le bloc cassé. |
| Posé | Nombre de placements réussis par le joueur avec un item de bloc, y compris en créatif. Une tentative refusée, une interaction ou un placement par commande ne compte pas. |
| En inventaire | Quantité actuellement dans l'inventaire personnel, équipement et curseur compris. Les coffres ouverts, ender chests et contenus imbriqués des boîtes ne sont pas inclus. |

Les blocs sont identifiés par leur identifiant de registre ; les propriétés
d'état (orientation, humidité, etc.) ne créent pas une nouvelle fiche. Deux
identifiants restent distincts : une torche murale peut être vue et posée tandis
que l'item possédé correspond à la torche debout. Les noms des blocs inconnus
restent consultables, comme un catalogue ; cette version ne décide pas d'une
politique de secrets ou de verrouillage des recettes.

L'inventaire est observé chaque tick serveur, après les transactions de menus
et avant la consommation d'un item placé. Les statistiques de ramassage/jet
complètent ce relevé. Une mutation d'inventaire entièrement réalisée entre ces
points par un autre mod ne peut pas être reconstruite après coup.
Les spectateurs ne découvrent pas de blocs par le regard.

## Persistance et arrivée dans une sauvegarde antérieure

Contrat additif v1 : fichiers `data/sanctuary-blocodex/<uuid>.json`, enveloppe
avec `schema: 1` et UUID, puis observations, possessions et poses par identifiant.
Les statistiques vanilla restent dans leurs propres fichiers et sont seulement
lues. Aucune conversion du terrain, des paramètres de génération, des chunks,
du journal d'expansion ou des statistiques existantes n'est effectuée.

Sans fichier Blocodex, les observations et poses commencent vides. Le minage,
le jet et les preuves de possession sont disponibles depuis les statistiques
vanilla déjà présentes. On n'invente pas les observations ni les poses passées
à partir de `used`, qui compte aussi d'autres usages.

Les changements sont sauvegardés tous les 600 ticks, lors de la sauvegarde du
serveur, à la déconnexion et à l'arrêt. Un crash peut perdre les dernières
observations ou poses non sauvegardées. Un fichier invalide ou d'une version
inconnue désactive la mémoire concernée et n'est jamais remplacé silencieusement.
Les identifiants de mods absents sont conservés sur disque. Les anciennes
versions de Sanctuary ignorent ce répertoire additionnel ; les poses réalisées
pendant un retour à une ancienne version ne peuvent pas être récupérées.

## Réutilisation

`BlockKnowledgeService.knowledge(player, block)` et `snapshot(player)` renvoient
des valeurs immuables calculées côté serveur. Le service expose aussi sa santé ;
un consommateur doit refuser une condition de progression si la mémoire est
indisponible, plutôt que d'interpréter une panne comme une découverte vierge.
`BlockKnowledgeEvents.CHANGED` permet de réagir aux observations, possessions,
poses et changements de statistiques. Les écouteurs s'exécutent sur le thread
serveur ; ils ne constituent pas un journal transactionnel de récompenses.

Cette livraison ne verrouille aucune recette et n'accorde aucune récompense.
Palettes disponibles, recherches, progression et structures pourront ensuite
définir leurs propres conditions en utilisant cette API commune.

### Palettes de structures

`BlockKnowledgeService.palette(player, condition, tag)` croise les connaissances
du joueur avec une famille de matériaux. Les critères `BlockKnowledgeFacet`
sont combinables avec `and` et `or` : vus **ou** déjà possédés, minés **et**
actuellement portés, etc. Le résultat immuable garde les identifiants triés et
les quantités réellement portées.

```java
var candidates = BlockKnowledgeService.palette(player,
        BlockKnowledgeFacet.SEEN.or(BlockKnowledgeFacet.POSSESSED),
        BlockKnowledgeService.NATURAL_STRUCTURE_MATERIALS);
```

Le tag `sanctuary:structure_palette/natural` fournit une première famille de
pierres, terres, bois, feuilles et autres matériaux naturels, modifiable par
datapack. D'autres tags pourront définir des palettes minérales, végétales ou
propres à un biome. Le choix des couleurs, les contraintes physiques des blocs,
les quantités nécessaires et la construction de la structure appartiendront au
moteur de structures : une sélection de palette ne réserve aucun stock et ne
place aucun bloc.

## Recensement du terrain chargé

`TerrainCensus.snapshot(server)` expose une distribution des blocs par dimension ;
`TerrainCensus.chunkSnapshot(level, pos)` fournit le détail d’un chunk déjà
chargé. Ces lectures se font sur le thread serveur et renvoient des valeurs
immuables. Elles parcourent les chunks `FULL` déjà accessibles, sans charger
de chunk absent ni attendre la fin d’une génération.

Le comptage utilise les palettes des sections de 16 × 16 × 16 blocs. Il regroupe
les orientations et autres propriétés sous l’identifiant du bloc. Les blocs
d’air sont exclus ; l’eau et la lave conservent leurs identifiants de blocs.
Le budget est de **16 sections non vides par tick serveur**, partagé entre les
dimensions et les demandes du même tick. Une section entièrement vide est
reconnue par ses métadonnées, sans parcourir sa palette.

Le relevé est progressif. Une section modifiée est retirée des totaux dès que
sa révision change, puis remise dans la file de comptage. Les sections et
chunks déchargés sortent du relevé. Un consommateur dispose, par dimension ou
chunk, du nombre de sections chargées et comptées, du tick de capture, du tick
du dernier comptage effectué et de l’âge de la plus ancienne attente.
`complete()` et `coverage()` décrivent la couverture **des zones chargées**.
Une couverture de 100 % ne signifie jamais que toute la sauvegarde a été lue.

Pendant un rattrapage, zéro bloc compté ne prouve donc pas l’absence de ce bloc.
Les futures règles d’expansion devront fixer leur couverture minimale et leur
zone d’étude avant de prendre une décision. Les résultats en mémoire sont
reconstruits après redémarrage ; ce service n’écrit pas dans les chunks et ne
modifie pas leur génération.

## Recensement des stocks présents

`StockCensus.snapshot(server)` photographie les objets accessibles au tick de
la demande, sur le thread serveur. Le parcours des slots et des entités chargées
est effectué à la demande ; aucun abonnement ne le relance à chaque tick.
Les quantités sont des unités d’items, tous
types confondus : un lingot, un outil ou une graine sont comptés même s’ils ne
correspondent pas à un bloc. Les composants, l’usure et les enchantements ne
créent pas de nouveaux identifiants de stock dans cette version.

| Catégorie | Couverture |
| --- | --- |
| `playerItems` | Joueurs connectés : inventaire personnel, équipement et curseur du menu. Le contenu du menu ouvert n’est pas additionné. |
| `blockContainerItems` | Entités de blocs déjà instanciées dans les chunks chargés, qui exposent l’interface `Container` : coffres, hoppers, fours, pots décorés, etc. Chaque moitié d’un double coffre est comptée une fois. |
| `entityContainerItems` | Entités chargées qui exposent `Container`, notamment les wagonnets et bateaux à coffre. |
| `groundItems` | Quantités des `ItemEntity` chargées et encore présentes au sol. |

Le relevé ne déballe **aucune table de butin**. Tout conteneur dont la table
reste à résoudre est ignoré avant la lecture de ses slots ; son existence
augmente `pendingLootContainers`. Les entités de blocs encore stockées sous
forme de NBT et non instanciées sont également laissées intactes, avec leur
nombre dans `pendingBlockEntities`. Leur contenu n’est pas remplacé par une
estimation.

La couverture exclut les joueurs hors ligne, les chunks et entités déchargés,
les ender chests, le contenu imbriqué des shulker boxes et bundles, les grilles
de fabrication en cours dans l’inventaire ou l’établi (`menuInputsIncluded()`
est faux), les inventaires et équipements des créatures. Le résultat de
fabrication affiché avant validation ne constitue pas un stock supplémentaire.
Elle exclut aussi les objets internes
des entités de blocs qui n’exposent pas `Container`, comme les aliments d’un feu
de camp ou le livre d’un pupitre. Une shulker box portée compte comme un item ;
une shulker box posée et chargée expose son conteneur. Les exclusions figurent
dans le contrat de couverture ; `partial()` reste vrai.

Ce relevé indique où se trouvent les unités observées. Il ne les réserve pas,
ne les transfère pas et n’évalue pas leur prix. Ajouter le terrain aux stocks
ne donne pas une quantité immédiatement vendable : une roche dans un chunk
reste différente d’un item dans un coffre.

## Consultation et futurs consommateurs communs

`WorldCensusService.capture(server)` rassemble les deux relevés pour une même
lecture côté serveur. Le consommateur réutilise cet instantané pendant son
calcul et conserve ses informations de couverture. Le shop et les expansions
pourront ainsi consulter la même base, avec leurs propres règles de fraîcheur,
de portée géographique, de prix, de consommation et de réservation.

Les diagnostics suivants sont réservés aux opérateurs :

```text
/sanctuary census
/sanctuary census block minecraft:stone
/sanctuary census item minecraft:gold_ingot
```

Le résumé présente la couverture du terrain par dimension, les quatre catégories
de stocks et les conteneurs au butin encore indéterminé. Le Blocodex personnel
accessible par **B** conserve les données du joueur ; ces diagnostics ne diffusent
pas les inventaires agrégés aux autres joueurs.

## Relevés datés — portée de l’alpha.23

La collecte regroupe les activités observées par **jour civil UTC**, pour
l’ensemble du serveur, sans attribution à un UUID ou à une dimension :

| Action | Registre et unité |
| --- | --- |
| `mined` | `block` : nombre de blocs minés, selon les règles des statistiques vanilla. |
| `placed` | `block` : placements réussis par le joueur, créatif inclus et spectateurs exclus. |
| `picked_up` | `item` : unités ramassées observées par les statistiques vanilla. |
| `dropped` | `item` : unités volontairement jetées observées par les statistiques vanilla. |
| `crafted` | `item` : unités fabriquées créditées au joueur par les statistiques vanilla. |

Chaque combinaison conserve son action, son registre, son identifiant et une
quantité entière sur 64 bits, saturée à la valeur maximale en cas de dépassement.
Un compteur de minage n’est pas transformé en nombre d’items produits. Les actions
antérieures à l’installation ne sont pas réparties artificiellement entre des
dates à partir des statistiques cumulées de Minecraft.

`MaterialActivityHistory.snapshot(server, day)` expose un instantané immuable
avec le jour, les compteurs, `recorded` et `unsaved`. Un jour sans données
enregistrées demeure inconnu ; il ne constitue pas un historique d’activité nulle.
Les opérateurs peuvent consulter `/sanctuary history` ou préciser une date avec
`/sanctuary history 2026-09-10`. La commande affiche au plus les 16 lignes aux
quantités les plus élevées et indique combien ont été omises ; l’API conserve
l’ensemble des compteurs du jour.

La persistance additionnelle utilise `data/sanctuary-activity/YYYY-MM-DD.json`,
avec un schéma 1 et des dates UTC. Elle est séparée de la mémoire personnelle
et des chunks. Les écritures ont lieu tous les **600 ticks**, à la sauvegarde
et à l’arrêt du serveur, ainsi qu’au changement de jour observé par le service.
Un crash peut perdre les derniers relevés non sauvegardés, soit normalement
jusqu’à 30 secondes de jeu à 20 ticks par seconde. Le fichier conserve les
identifiants de mods absents ; il refuse les schémas inconnus, doublons,
compteurs invalides et changements externes. Une erreur arrête la collecte et
rend le service indisponible jusqu’à réparation puis redémarrage, en conservant
le fichier en cause. Les limites sont de 100 000 tuples et 16 Mio par jour.

Ces relevés permettent de distinguer des périodes d’activité. Ils ne conservent
pas d’historique des instantanés de stocks, ne couvrent pas la fabrication automatique des
machines et n’établissent ni consommation, ni perte, ni destination des objets.
Ils ne retracent pas chaque transfert entre coffres ou chaque changement de propriétaire, et
ne constituent pas un journal transactionnel d’achats, de récompenses ou de
réservations. Le **ballast**, ses unités, ses conversions et sa traduction en
géologie restent à concevoir dans le [cahier de cosmologie](cosmologie.md).
Aucun objet n’est consommé et aucune Backroom n’est générée par ces mesures.

## Référence WSMC retrouvée

La recherche locale a retrouvé une partie du travail précédent dans
`/Users/koka/Documents/sanctuary/Gameplay/blocodex` :
`ClientVoxelProjectBuilder` convertit des apparences de blocs et d’items en
volumes/couches de blocs ; `BlocodexStudioPalettes` sélectionne des matériaux
opaques appris. Le projet conserve aussi un instantané WSMC de 1 881 entrées
(1 168 blocs, 490 items, 223 mobs), issu de Minecraft 1.21.11.

Cette référence reste historique. La nouvelle API fournit la connaissance et
les candidats de palette ; la traduction de modèles d’entités en structures
(visage de creeper, squelette géant, etc.) reste un chantier distinct. Aucun
générateur d’entités ni import de ce snapshot ancien n’est ajouté au registre
de Minecraft 26.3 par le socle méta.

## Validation

Validation locale du 10 septembre 2026 : `./gradlew check build assemblePack`
passe, avec **24 GameTests natifs réussis**. Le client graphique vérifie les
widgets et les messages réels dans un nouveau monde intégré, avec B sans droit
opérateur, observation serveur et possession conservée après retrait du stock.
Les tests de stockage passent. Les [preuves et limites](testing-alpha23.md)
détaillent le protocole, l’artefact et son empreinte. Alpha.23 assemblée localement ;
publication du MRpack et mise à jour du canal demandées, en préparation.