Premier commit

Cette révision appartient à :
Théo Gastinel a révisé 2026-10-11 01:54:18 +02:00
révision 84a72fe30c
200 fichiers modifiés
+61602

Aucun fichier ne correspond à votre recherche

+320
Voir le fichier
@@ -0,0 +1,320 @@
# Phase 28 — Conception de l'artisanat diégétique (document de conception, aucun code)
Rédigé le 2026-09-27, en session sans supervision. Toutes les références
`fichier:ligne` ont été relues dans l'état actuel du dépôt (après
`3faf930`, fin de Phase 27). Aucune ligne de code n'a été modifiée ; aucun
build n'a été lancé.
**Document de cadrage d'origine : introuvable.** Il n'existe aucun fichier de
cadrage dans le dépôt ; il n'est connu que par citations (`MEMORY.md:14`,
`MEMORY.md:1825`, `NOTES-PHASE22.md:106`, « les trois matières du document de
cadrage qui manquaient »). Les exemples « outils primitifs, ligatures en fibres,
poix (résine + cendres), manches en bois dense » viennent donc de la consigne
de la Phase 28, pas d'une relecture du cadrage.
---
## 1. Inventaire vérifié
### 1.1 Le modèle d'objet commun : `GroundItem` + `Ground` + `Inventory`
| Élément | Référence | Ce qu'il fait |
|---|---|---|
| `enum class GroundItemKind : uint8_t` | `src/world/GroundItem.hpp:13-28` | 8 valeurs : `Log, Branch, Stone, Flake, Clay, Sand, Resin, Fiber` |
| `kGroundItemKindCount = 8` | `GroundItem.hpp:30` | **Taille codée en dur** de l'inventaire — à incrémenter avec chaque nouveau type |
| `groundItemRestRadius`, `groundItemLabel*` | `GroundItem.hpp:34-46` | Rayon de repos et libellés FR (sing./indéfini/pluriel), un `switch` par type dans `Ground.cpp` |
| `struct GroundItem {position, yaw, roll, kind}` | `GroundItem.hpp:51-58` | Objet couché, mesh à dimensions absolues, jamais mis à l'échelle |
| `Ground::drop(kind, x, z, yaw, roll)` | `src/world/Ground.hpp:37` | Pose à la surface (le Ground calcule Y) |
| `Ground::scatterStones` | `Ground.hpp:43` | Semis initial des pierres |
| `Ground::findNearest(pos, reach, vTol=3)` | `Ground.hpp:53` | Portée **horizontale**, un seul objet, tous types confondus |
| `Ground::pickUp(index, kindOut)` | `Ground.hpp:58` | Retire l'objet du monde |
| `Ground::items()` | `Ground.hpp:60` | Accès en lecture au vecteur — suffit pour une requête « objets de tel type dans un rayon » |
| `Inventory::add / count / remove / summary` | `src/world/Inventory.hpp:20, 24, 31, 49` | Simples **compteurs** par `GroundItemKind`, `remove` atomique (refuse sans rien toucher) |
Il n'existe **aucun** geste « reposer au sol » depuis l'inventaire (grep de
`inventory.remove` dans `main.cpp` : seul le taillage consomme). Il n'y a **pas
de notion d'objet tenu** distincte de l'inventaire : « porter » = être compté
dans `Inventory`. Pas de masse, pas d'encombrement (`Inventory.hpp:1-17`,
commentaire d'en-tête : « le jour où le portage à dos sera un vrai sujet, c'est
cette classe qui grossira »).
### 1.2 Les matériaux
| Matériau | `GroundItemKind` | Récolte (touche) | Fichiers / fonctions |
|---|---|---|---|
| Bûche | `Log` | Abattage **E** (`kFellKey`, `main.cpp:185`) : `Forest::pickTree` puis `Forest::fell` (`main.cpp:3016-3043`, `Forest.hpp:136`). Débitage différé : `Forest::scheduleBucking` (`Forest.cpp:589`), 2 à 4 bûches selon la hauteur (`Forest.cpp:606`), déposées par `advancePendingDrops` → `ground_.drop` (`Forest.cpp:507`). `Habitat::recordFelling` inscrit la coupe (`main.cpp:3033`) |
| Branche | `Branch` | Même chaîne que la bûche (houppier), `Forest::scheduleBucking` |
| Pierre | `Stone` | Semée par `Ground::scatterStones` ; ramassage **R** (`main.cpp:3049-3062`) |
| Éclat | `Flake` | Taillage **C** (`kKnapKey`, `main.cpp:187`) : `knapStones` (`src/world/Knapping.cpp:32-60`) |
| Argile | `Clay` | Creuser **Y** (`kDigKey`, `main.cpp:260`) près d'un gisement `DepositKind::Clay` : `findMineralDeposits` / `nearestDeposit` (`src/world/Deposits.hpp:165, 180`), portée `kDigReach = 3,5 m` (`Deposits.hpp:175`) ; dépôt au sol `main.cpp:2343-2379` |
| Sable | `Sand` | Idem, gisement `DepositKind::Sand` (loin de l'eau) |
| Résine | `Resin` | Saigner **U** (`kResinKey`, `main.cpp:261`) : `ResinStand::tap(treeIndex, species, now)` (`src/world/Resin.hpp:102`) ; 600 s entre deux saignées, 3 par arbre ; dépôt au pied de l'arbre `main.cpp:2385-2421` |
| Fibres | `Fiber` | Arracher **I** (`kFiberKey`, `main.cpp:262`) : `FiberPlants::pullNearest` (`src/world/FiberPlants.hpp:208`), portée `kPullReach = 2,5 m` (`:163`), repousse 420 s (`:129`) ; `main.cpp:2429-2451` |
Règle commune posée en Phase 6 et répétée en Phase 22 (`Knapping.hpp:36-40`,
`GroundItem.hpp:18-23`, `main.cpp:2337-2342`) : **ce qui est produit tombe
d'abord au sol**, jamais directement dans l'inventaire.
### 1.3 Le pattern Knapping (le modèle à généraliser)
`knapStones(Inventory&, Ground&, playerPos, facing)` (`Knapping.hpp:43`,
`Knapping.cpp:32`) :
1. vérifie les ingrédients dans l'inventaire (`count(Stone) < 2`, `.cpp:34`) ;
2. projette le regard à l'horizontale, **teste la longueur avant de normaliser**
(`.cpp:41-43`) ;
3. consomme **un seul** ingrédient — le nucleus ; le percuteur est un **outil
non consommé** (`.cpp:47`, justification `.hpp:29-32`) ;
4. dépose le produit à 1,1 m devant le joueur (`kDropDistance`, `.cpp:14`,
`ground.drop` `.cpp:57`) ;
5. renvoie un `enum` de résultat + `knapResultMessage` (message FR journalisé).
Aucune table de recettes « volontairement » (`Knapping.hpp:26-27`).
`creuser` (`main.cpp:2343`) duplique à la main la même projection + dépôt à
1,1 m : c'est un **deuxième exemplaire** du même geste, déjà factorisable.
### 1.4 Systèmes qu'un objet fabriqué peut influencer
| Système | Point d'ancrage réel | État |
|---|---|---|
| **Needs — abri** | `NeedsContext::sheltered` (`src/world/Needs.hpp:126`) ; effet `shelterWarmthC = 5 °C` (`Needs.hpp:220`), et annule le refroidissement éolien (`Needs.cpp:184-191`) | **Aucun appelant** (`MEMORY.md:1278`) : `main.cpp:2276-2299` ne le remplit jamais |
| **Needs — température** | `NeedsContext::ambientTemperatureC` rempli depuis `WeatherSample::temperatureC` (`main.cpp:2284`) ; `NeedsParams::comfortTemperatureC`, `exertionWarmthCPerEffort` | Aucune source de chaleur locale n'existe |
| **Needs — soif** | `Needs::drink()` (`Needs.cpp:269`) remet la soif à 1 ; appelé seulement à `kDrinkReach` d'un point d'eau (`main.cpp:2313-2322`) | Pas de contenant : on ne boit qu'au point d'eau |
| **Needs — faim** | `Needs::eat(nutrition)` (`Needs.cpp:277`) | **Aucun appelant**, rien de comestible n'existe (`MEMORY.md:1274`) |
| **Needs — vitesse** | `Needs::movementFactor()` (`Needs.hpp:375`) module la marche | — |
| **Lumière / nuit** | `WeatherParams::nightAmbientFactor = 0,30` (`src/world/Weather.hpp:405`), `sunLightFor` (`Weather.hpp:933`) ; « à revoir avec le feu de camp » (`MEMORY.md:2214`) | **Aucune lumière ponctuelle** dans le renderer (grep `fire/feu/foyer` : zéro) |
| **Vitesse d'abattage** | `Forest::fell` est **instantané** (`main.cpp:3025`) ; seul le débitage a un délai (`PendingDrop::delay`, `Forest.hpp:163`) ; portée `kFellingReach = 40 m` (`main.cpp:170`) | **Il n'y a pas de vitesse d'abattage** ; et abattre ne demande aucun outil |
| **Vitesse de taillage** | `knapStones` est instantané | Pas de durée non plus |
| **Rendement** | `logCount = clamp(h/2,4, 2, 4)` (`Forest.cpp:606`) | Quantité modulable sans nouveau système |
| **Sauvegarde** | Aucune sauvegarde de partie. Seul `F5` écrit la scène de l'éditeur (`main.cpp:320`, `src/editor/SceneFile.cpp`). « Rien n'est sauvegardé » (`MEMORY.md:1957`, `NOTES-PHASE22.md` fin) | Inexistant |
| **Tests headless** | `tests/logic_tests.cpp` : `testPickup` (l.477), `testStoneKnapping` (l.652), `testNeeds` (l.5158), `testMineralDeposits` (l.6788), `testResin` (l.6999), `testFiberPlants` (l.7177) ; lancés par `tools\run_logic_tests.bat` | 3578 assertions (chiffre de la Phase 23) |
**Conséquence de conception majeure** : il n'existe ni feu, ni cendres, ni
vitesse d'abattage/taillage, ni sauvegarde. La « poix (résine + cendres) » du
brief suppose un **foyer** qui n'existe pas : le foyer doit donc être lui-même le
premier objet fabriqué, et c'est lui qui produira les cendres.
---
## 2. Les objets fabricables (8), et la priorité
Convention : **« posé »** = objet `Ground` à portée de l'ouvrage ; **« porté »**
= compté dans `Inventory` ; **« outil »** = requis mais non consommé (règle du
percuteur, `Knapping.hpp:29-32`).
### P1 — Foyer (`GroundItemKind::Hearth`, nouveau) — **prioritaire**
- **Ingrédients** : 3 pierres **posées** (consommées) + 2 branches **posées**
(consommées).
- **Interaction** : le joueur pose lui-même pierres et branches au sol, se place
au-dessus et fait le geste d'assemblage (touche d'artisanat, cf. §3.3). Pas
d'allumage séparé cette phase : le foyer est allumé à la construction avec
l'éclat comme outil (percussion pierre/éclat = étincelle, même geste que le
Knapping, **éclat porté, non consommé**).
- **Effet** : `NeedsContext::ambientTemperatureC += hearthWarmthC` (proposé
8 °C, décroissant linéairement jusqu'à 6 m) pendant la durée de combustion
(proposée 1 h de jeu, prolongée d'1 h par branche ou bûche posée dans le
foyer). Branché dans `main.cpp:2284`, **même calcul de température unique** :
on corrige l'ambiante locale, on ne crée pas une seconde formule.
Produit **1 cendre** (`GroundItemKind::Ash`, nouveau) à son extinction, posée
au centre.
- **Lien matière** : pierres = cercle de foyer, branches = combustible ; les
bûches (trop grosses pour allumer) servent seulement à l'entretien.
- **Lumière** : **pas cette phase** (le renderer n'a pas de lumière ponctuelle).
Décision documentée en §4.
### P2 — Ligature de fibres (`Cord`, nouveau) — **prioritaire**
- **Ingrédients** : 3 fibres **portées**, consommées.
- **Interaction** : torsion à la main, geste identique au Knapping (depuis
l'inventaire, produit déposé à 1,1 m devant). Aucun poste.
- **Effet** : aucun direct — c'est l'intermédiaire obligatoire de P3, P5 et P6.
Le justifier comme objet et non comme étape cachée est ce qui rend la chaîne
visible au sol.
- **Lien matière** : ortie et ronce sont des sources de fibres textiles réelles.
### P3 — Hache emmanchée (`Axe`, nouveau) — **prioritaire**
- **Ingrédients** : 1 éclat + 1 branche + 1 ligature, **posés ensemble** (outil
composite = assemblage au sol, pas en poche). Tous consommés.
- **Interaction** : assemblage au sol à la touche d'artisanat ; même dépôt que
le Knapping.
- **Effet** : l'abattage n'ayant pas de durée, deux effets réels possibles ;
retenu : **rendement** — `Forest::scheduleBucking` donne +1 bûche
(`clamp(…, 3, 5)` au lieu de `2, 4`, `Forest.cpp:606`) si une hache est portée.
Option non retenue : rendre `fell` impossible sans hache (voir §4, risque de
régression du scénario Vulkan A).
- **Lien matière** : éclat = tranchant, branche = manche, fibre = ligature.
### P4 — Poix (`Pitch`, nouveau) — **prioritaire (dernier des quatre)**
- **Ingrédients** : 2 résines + 1 cendre, **posées près d'un foyer allumé**.
- **Interaction** : le foyer est le **poste** : on pose résine et cendre à moins
de 2 m d'un foyer en combustion et on fait le geste d'artisanat. Refus
journalisé « il faut chauffer la résine » sinon.
- **Effet** : ingrédient de P5 et P6 (colle imperméable) ; remplace la ligature
seule dans la hache renforcée (voir P5).
- **Lien matière** : la poix de résine + charbon/cendre est la colle
préhistorique attestée.
### P5 — Hache renforcée (poix) — secondaire
- 1 hache + 1 poix, posées. Effet : +2 bûches au lieu de +1. Pas d'usure
cette phase, donc l'intérêt est modeste : secondaire.
### P6 — Abri de branches (`Shelter`, nouveau) — secondaire, fort impact
- **Ingrédients** : 4 bûches + 6 branches + 2 ligatures, posés.
- **Interaction** : assemblage au sol ; l'abri devient un objet **non
ramassable** du Ground (voir §3.4).
- **Effet** : `NeedsContext::sheltered = true` quand le joueur est à moins de
2,5 m d'un abri — premier appelant de ce champ (`Needs.hpp:126`), +5 °C et
vent annulé (`Needs.cpp:184-191`). C'est l'usage des bûches annoncé en
`MEMORY.md:1718`.
- Repoussé car il demande une collision (l'abri doit être solide) et un mesh.
### P7 — Pot d'argile cuite (`ClayPot`, nouveau) — secondaire
- **Ingrédients** : 2 argiles + 1 sable (dégraissant), façonnés au sol, puis
**cuits** en restant posés 10 min de jeu à côté d'un foyer allumé
(transformation `RawPot → ClayPot` pilotée par le temps, même horloge
`elapsedSeconds` que `ResinStand`).
- **Effet** : rempli au point d'eau (touche **T**, `main.cpp:2313`), il permet
un `Needs::drink()` hors de portée d'eau (une gorgée par remplissage).
- **Lien matière** : le sable est le dégraissant qui empêche l'argile de se
fendre à la cuisson.
### P8 — Couteau à éclat emmanché — rejeté pour cette phase
Éclat + branche + ligature. Aucun système existant qu'il influencerait (pas de
dépeçage, pas de nourriture) : **écarté** selon la règle « aucune mécanique
déconnectée ». Listé pour mémoire.
**Les 4 prioritaires cette session : Foyer (P1), Ligature (P2), Hache (P3),
Poix (P4).** P1 donne le premier effet réel sur Needs et produit la cendre ; P2
et P3 débloquent la chaîne outil ; P4 exerce le « poste » (foyer) et termine la
chaîne cendre du brief.
---
## 3. Architecture : un craft générique qui étend Knapping, pas un système parallèle
### 3.1 Principe
Un nouveau module `src/world/Crafting.hpp/.cpp`, **sans Vulkan**, calqué sur
`Knapping` : une fonction libre qui prend `Inventory&`, `Ground&`, la position et
le regard, et renvoie un résultat + message. `knapStones` devient la **recette
n°0** exprimée dans la table (le test `testStoneKnapping` doit rester vert sans
modification, garde-fou de non-régression). La touche **C** reste la touche
unique du geste de « façonner » : pas de nouvelle touche, pas de menu.
### 3.2 Structure d'une recette
```
struct Ingredient { GroundItemKind kind; uint8_t count; Source source; bool consumed; };
enum class Source : uint8_t { Carried, Placed, Either };
enum class Station : uint8_t { None, LitHearth };
struct Recipe {
const char* id; // "hearth", "cord", ... (stable, sert aux logs/tests)
std::array<Ingredient, 4> in; uint8_t inCount;
GroundItemKind out; uint8_t outCount;
Station station; // poste requis à portée
float stationReach; // 2 m
const char* successMessage; // FR, même rôle que knapResultMessage
};
inline constexpr std::array<Recipe, N> kRecipes = {...}; // constexpr, pas de fichier externe
```
Table **constexpr** dans le code : testable, sans parsing, cohérente avec la
philosophie « paramètres regroupés et documentés » (`WeatherParams`, `NeedsParams`).
### 3.3 Détection et déclenchement
`CraftResult craftAt(Inventory&, Ground&, const CraftWorld&, pos, facing)`
où `CraftWorld` expose les postes (foyers allumés = objets `Hearth` du Ground
avec combustion > 0).
1. Collecte des objets **posés** : nouvelle méthode
`Ground::indicesWithin(pos, reach=2,5 m, vTol)` — même critère horizontal
que `findNearest` (`Ground.hpp:53`), mais renvoie tous les indices.
2. **Sélection de la recette** : on parcourt la table dans l'ordre de
**priorité décroissante de complexité** (abri avant hache avant ligature avant
percussion), et on prend la première satisfaite. Déterministe ; l'ordre est
la seule règle, documentée. Le joueur choisit donc la recette **en
choisissant ce qu'il pose** — c'est le geste diégétique.
3. Refus : si aucune recette n'est satisfaite, message sur la recette « la plus
proche » (celle dont il manque le moins d'ingrédients) : « il manque une
ligature », sur le modèle du refus avec distance de `creuser`
(`main.cpp:2349-2353`).
### 3.4 Consommation et création
- Tout est vérifié **avant** tout retrait (atomicité, même discipline que
`Inventory::remove`, `Inventory.hpp:28-30`). Retraits Ground par indices triés
**décroissants** (sinon `pickUp` décale les indices).
- Produit : `ground.drop(out, …)` à 1,1 m devant (portée de `kDropDistance`
réutilisée) — ou, pour un produit d'assemblage au sol, au **barycentre** des
ingrédients consommés : l'objet naît là où on l'a construit.
- Objets fixes (`Hearth`, `Shelter`) : ajout de `groundItemIsPortable(kind)`
dans `GroundItem.hpp` ; `findNearest` les ignore pour le ramassage.
- État propre au foyer (combustion restante) : un `HearthSet` séparé (indice
d'objet → secondes restantes), sur le modèle de `ResinStand` qui garde « la
mémoire des arbres saignés » hors de la Forest. `GroundItem` reste un POD
sans état.
- Alimenter un foyer = poser une branche/bûche à moins de 1 m puis **C** : c'est
une recette `Branch(Placed) + Station LitHearth → rien` avec effet
`+1 h`. Pas de cas particulier.
### 3.5 Branchement des effets
- Chaleur : dans `main.cpp` à côté de `main.cpp:2284`,
`ambientTemperatureC += hearthSet.warmthAt(playerPosition)`. Fonction pure,
testable.
- Hache : `Forest::scheduleBucking` reçoit un `bonusLogs` (0 par défaut) —
défaut = comportement actuel au bit près.
- Abri (P6, plus tard) : `needsContext.sheltered = shelterNear(...)`.
### 3.6 Sauvegarde
Aucune sauvegarde de partie n'existe ; **la Phase 28 n'en crée pas** (décision
§4). Préparation : `Recipe::id` stables, et `HearthSet` exprimé en temps de
jeu, pour qu'un futur format texte (modèle `SceneFile`/`.vcsc`) puisse écrire
`Ground::items()` + l'état des foyers sans changer de structure.
### 3.7 Tests headless à prévoir (`tests/logic_tests.cpp`)
- `testCraftingRecipeTable` : unicité des `id`, sorties hors ingrédients, ordre
de priorité respecté.
- `testCraftingKnapUnchanged` : la recette n°0 reproduit exactement
`testStoneKnapping` (2 pierres, 1 consommée, éclat à 1,1 m, regard vertical
→ repli sans NaN).
- `testCraftingAtomicity` : ingrédient manquant ⇒ Inventory et Ground
**identiques** octet pour octet.
- `testCraftingPlacedVsCarried` : un ingrédient `Placed` hors portée (2,6 m) ne
compte pas ; un `Carried` au sol ne compte pas.
- `testCraftingIndexRemoval` : consommation de plusieurs objets Ground non
contigus sans décalage.
- `testHearth` : chaleur maximale au centre, nulle à 6 m, extinction ⇒ cendre
déposée, alimentation prolonge ; foyer non ramassable.
- `testPitchNeedsLitHearth` : refus sans foyer, refus foyer éteint, succès.
- `testAxeYield` : `bonusLogs = 0` ⇒ `logCount` identique à avant ;
`= 1` ⇒ 3..5.
- `testNeeds` inchangé (garde-fou : ambiante non corrigée hors foyer).
- Vulkan : un scénario K optionnel (pierres + branches semées au départ, **C**,
vérifier le foyer dans le journal) — non bloquant cette phase.
---
## 4. Décisions prises par défaut et risques
| Décision | Justification |
|---|---|
| Foyer créé en P1 alors que le brief cite seulement la poix | La poix exige des cendres ; rien n'en produit. Inventer des cendres sans feu serait une mécanique déconnectée |
| Pas de lumière du foyer | Le renderer n'a aucune lumière ponctuelle ; l'ajouter est un chantier de rendu (UBO, 3 shaders) hors conception d'artisanat. `nightAmbientFactor` reste inchangé |
| Allumage inclus dans l'assemblage (éclat outil) | Évite un second geste et un état « foyer éteint neuf » sans usage |
| Hache = rendement, pas condition d'abattage | L'abattage est instantané et sans outil ; le rendre conditionnel casserait le scénario Vulkan A et le mode démo |
| Même touche **C** pour tout le façonnage | Zéro menu : la recette se choisit par ce qu'on pose, pas par une liste |
| Recettes en table constexpr | Testable, sans fichier de données à charger |
| Pas de sauvegarde | Aucune n'existe dans le jeu ; en créer une est une phase à part entière |
| Pas d'usure des outils | Aucune notion d'usure dans le jeu (`MEMORY.md:774`) |
| Couteau écarté | Aucun système à influencer |
**Risques de régression**
- `kGroundItemKindCount` (`GroundItem.hpp:30`) et tous les `switch` de
`Ground.cpp` (libellés, rayons) et des meshes (`StoneMesh`, `TreeMesh`,
`HarvestMesh`) : chaque nouveau type doit y être ajouté, sinon mesh ou libellé
manquant. Un test doit itérer sur tous les types.
- `Inventory::summary()` s'allonge (titre de fenêtre) : afficher seulement les
compteurs non nuls.
- Réécrire `knapStones` via la table : risque sur `testStoneKnapping` et les
scénarios A/B → garder `knapStones` comme façade.
- `findNearest` modifié pour ignorer les objets fixes : risque sur `testPickup`.
- Chaleur du foyer ajoutée à l'ambiante : vérifier que `testNeeds` et le scénario
H ne voient aucun foyer (valeur par défaut 0).
- Mode démo (`main.cpp:3010-3014`) : le façonnage doit rester coupé comme le
taillage.
- Portage : objets « posés » requis ⇒ il faut un geste pour **reposer** un
objet porté (absent aujourd'hui). À ajouter en même temps (proposé : **R**
maintenu = poser le dernier type ramassé), sinon P1 et P3 sont injouables.