(Feat) Add footsteps

2026-08-11 15:23:10 +02:00
parent e8e128457a
commit 176beab9fc
4776 changed files with 18806 additions and 121 deletions
@@ -0,0 +1,405 @@
+# Customisation de personnage
+
+Le joueur choisit sa silhouette, son visage, sa coiffure et ses couleurs avant
+de lancer une partie. Les trois autres joueurs le voient tel qu'il s'est fait.
+
+Ce document a **deux moitiés**, à lire séparément :
+
+- **Partie A — pour l'artiste** : ajouter une coiffure, une couleur, un corps.
+  Aucune ligne de code, aucune recompilation. Commence au §1.
+- **Partie B — pour le développeur** : architecture, réseau, pièges du moteur.
+  Commence au §6.
+
+---
+
+# PARTIE A — Ajouter du contenu
+
+## 1. Le principe en une phrase
+
+**Tout passe par un seul asset : `DA_CharacterParts`.** C'est la table qui dit
+« l'option n° 3 de la catégorie Cheveux, c'est ce mesh-là ». Le code ne connaît
+que des numéros ; c'est le catalogue qui leur donne un sens.
+
+Conséquence directe : **ajouter du contenu ne demande jamais de toucher au
+code**, et jamais de fermer l'éditeur.
+
+```
+DA_CharacterParts
+├── Body Sets              une entrée par silhouette (A, B, …)
+│   ├── Body Meshes        les morceaux du corps
+│   ├── Anim Class         l'AnimBP qui l'anime
+│   ├── Heads              ┐
+│   ├── Hairstyles         │ les listes d'options,
+│   ├── Eyebrows           │ propres à CETTE silhouette
+│   ├── Beards             │
+│   └── Mustaches          ┘
+└── Palettes               partagées par toutes les silhouettes
+    ├── Skin Colors
+    ├── Hair Colors
+    ├── Eye Colors
+    ├── Underwear Colors
+    └── Eye Materials
+```
+
+## 2. Ajouter une coiffure
+
+1. Ouvre `Content/Game/Data/Character/DA_CharacterParts`
+2. Déplie **Body Sets** → l'entrée du corps concerné (`[0]` = A, `[1]` = B)
+3. Déplie **Hairstyles** → clique le **+**
+4. Dans la nouvelle entrée :
+   - **Mesh** = ton `SKM_…`
+   - **Icon** = la vignette (facultative, voir §5)
+5. Sauvegarde
+
+C'est tout. La coiffure apparaît dans l'écran au prochain lancement.
+
+> **L'ORDRE DE LA LISTE EST LE CONTRAT.** Un index est ce qui part sur le réseau
+> et ce qui se sauvegarde. **Insérer une entrée au milieu décale tout ce qui
+> suit** : les personnages déjà créés changeront de coiffure sans prévenir.
+> **Ajoute toujours à la fin.**
+
+Même procédé pour **Heads**, **Eyebrows**, **Beards**, **Mustaches**.
+
+## 3. Ajouter une couleur
+
+1. Déplie **Palettes** → la palette voulue (`Skin Colors`, `Hair Colors`…)
+2. Clique le **+**
+3. Double-clique la case de couleur → dans le picker, colle une valeur dans le
+   champ **Hex sRGB** (le plus fiable) ou règle R/G/B à la main
+4. Sauvegarde
+
+Les palettes sont **partagées par toutes les silhouettes** : une teinte de peau
+ajoutée profite à A comme à B. Deux nuanciers à tenir à jour divergeraient au
+premier ajout.
+
+> Même règle d'ordre qu'au §2 : **on ajoute à la fin**.
+
+### Ce que chaque palette pilote
+
+| Palette | Ce qu'elle teint |
+|---|---|
+| **Skin Colors** | le corps **et** le visage, ensemble |
+| **Hair Colors** | cheveux, **barbe, moustache et sourcils** en même temps |
+| **Eye Colors** | l'iris |
+| **Underwear Colors** | le sous-vêtement |
+
+Une barre de couleur de cheveux qui ne teindrait pas la barbe donnerait un
+personnage incohérent — c'est voulu qu'elles suivent.
+
+## 4. Ajouter une silhouette
+
+Plus lourd, mais toujours sans code.
+
+1. **Body Sets** → **+** → une nouvelle entrée
+2. **Body Meshes** → ajoute ton `SKM_` de corps (une seule case aujourd'hui)
+3. **Anim Class** → l'AnimBP à utiliser
+
+> **Tu peux réutiliser `ABP_PlayerBody_A`** si ton nouveau corps partage les
+> mêmes **noms d'os**. Le moteur valide la compatibilité par les noms, pas par
+> l'identité du squelette. C'est ce qui permet à Body A et Body B de partager un
+> seul AnimBP : une correction profite aux deux.
+
+4. Remplis **Heads**, **Hairstyles**, **Eyebrows** — ces listes appartiennent à
+   la silhouette
+5. Laisse **Beards** et **Mustaches** vides si elle n'en porte pas : les
+   catégories **disparaissent d'elles-mêmes** de la colonne de l'écran
+
+## 5. Les vignettes
+
+Le champ **Icon** est un `UTexture2D`, exactement comme l'icône d'un objet
+d'inventaire.
+
+**Il est facultatif.** Une entrée sans vignette affiche son **numéro** dans la
+case — l'option reste choisissable. C'est délibéré : le catalogue doit rester
+utilisable avant que les trente-six vignettes existent, et le moyen le plus
+simple de les fabriquer est justement de capturer l'écran de customisation une
+fois qu'il tourne.
+
+## 6. Le décor de l'écran
+
+Le personnage montré pendant la customisation est un acteur posé dans
+`MenuScene` : **`BP_CharacterPreview`**. Trois choses comptent quand tu le
+places :
+
+- **Hors du champ des `MenuCameraSpot`**, sinon il apparaît en arrière-plan du
+  menu principal
+- **Devant un fond qui tient debout** — c'est ce qu'on voit derrière lui pendant
+  toute la customisation
+- **Éclairé de face.** On passe l'essentiel du temps en gros plan sur le
+  visage ; à contre-jour, les teints de peau deviennent illisibles et c'est
+  précisément ce que le joueur règle
+
+### Les deux cadrages
+
+`FullBodyViewSpot` et `FaceViewSpot` sont deux repères vides que tu **déplaces à
+la souris** dans le viewport du Blueprint. La caméra glisse de l'un à l'autre
+selon la catégorie ouverte :
+
+| Catégorie ouverte | Cadrage |
+|---|---|
+| Silhouette, Teint, Sous-vêtement | `FullBodyViewSpot` |
+| tout le reste | `FaceViewSpot` |
+
+Pense à **décaler le personnage vers la droite** de l'image : la colonne d'UI
+occupe la gauche.
+
+---
+
+# PARTIE B — Architecture
+
+## 7. Vue d'ensemble
+
+| Fichier | Rôle |
+|---|---|
+| `CharacterAppearanceTypes.h` | `FCharacterAppearance` (11 octets), les enums, `FCharacterPartEntry` |
+| `CharacterPartsDataAsset` | le catalogue : index → assets, palettes, noms de paramètres matériau |
+| `CharacterAppearanceComponent` | monte les pièces, pose les couleurs. Sur le pawn **et** sur le mannequin |
+| `CharacterPreviewActor` | le mannequin du menu : mesh + caméra + cadrages |
+| `CharacterCustomizationWidget` | l'écran, la colonne, la grille |
+| `CustomizationCategoryWidget` | une rangée de la colonne |
+| `CustomizationOptionWidget` | une case : vignette **ou** pastille |
+| `SurvivalPlayerState` | porte l'apparence répliquée |
+| `SurvivalUserSettings` | la persiste dans le `.ini` |
+
+## 8. `FCharacterAppearance` — pourquoi des index
+
+11 octets, **que des index**, jamais de `TSoftObjectPtr` ni de chemin d'asset.
+Deux raisons qui vont dans le même sens :
+
+- un chemin coûte une chaîne à chaque réplication, un index tient dans un octet ;
+- un index se **valide** contre le catalogue, alors qu'un chemin envoyé par un
+  client pourrait désigner n'importe quel asset du jeu.
+
+Bénéfice collatéral : la struct se sérialise telle quelle dans le `.ini`
+(`CharacterAppearance=(BodyType=BodyA,HeadIndex=0,…)`). Une apparence faite de
+références d'assets aurait donné une douzaine de chemins à écrire, qu'une seule
+renommée aurait cassés silencieusement.
+
+`NoPart` vaut **255** : c'est « aucune pièce », pour une barbe rasée.
+
+## 9. Le montage — `UCharacterAppearanceComponent`
+
+Un `USkeletalMeshComponent` par catégorie, enfant du mesh porteur, en **Leader
+Pose**. Un seul mesh porte l'animation, les autres recopient sa pose **par nom
+d'os** — ce qui marche même entre squelettes distincts.
+
+Le composant recopie sur chaque pièce le `bOwnerNoSee` et le `bCastHiddenShadow`
+du porteur. C'est ce qui fait que le **mannequin du menu est visible** sans une
+ligne de code de plus, alors que le corps du joueur reste invisible à son
+propriétaire.
+
+### Le corps se monte depuis une LISTE
+
+`BodyMeshes` est un `TArray` même s'il ne contient qu'une case. Le pack livre
+exprès `SKM_BodyA_torso`, `_arms`, `_legs_01/02/03`, `_hands`, `_feet` : le jour
+où une armure devra cacher les segments qu'elle recouvre, la case 0 deviendra
+`SKM_BodyA_empty` — porteur d'animation invisible — et les huit segments
+suivront derrière, **sans que ce code change**.
+
+> **Contrainte à vérifier avant tout achat de pack d'armure : il doit être
+> skinné sur `SK_BodyA` / `SK_BodyB`.**
+
+### Les couleurs
+
+Chaque paramètre est posé sur **tous les éléments** de chaque mesh, sans chercher
+lequel le porte : un `SetVectorParameterValue` dont le paramètre n'existe pas est
+simplement ignoré. Le slot des yeux ignore donc `Skin`, celui de la peau ignore
+`Eye color`. Cela évite une table d'index de slots qui casserait au premier mesh
+mal rangé.
+
+## 10. Réseau et persistance
+
+```
+   USurvivalUserSettings  ──lit──►  AnnounceCharacterAppearance()
+       (.ini du joueur)                       │
+                                              ▼
+                              SubmitCharacterAppearance()   ← POINT D'ENTRÉE UNIQUE
+                                    │                │
+                              persiste          Server_SetCharacterAppearance
+                                                     │
+                                          ASurvivalPlayerState (autorité)
+                                                     │
+                                          ┌──────────┴──────────┐
+                                    OnRep (clients)      appel direct (hôte)
+                                          └──────────┬──────────┘
+                                                     ▼
+                                          ApplyAppearanceToPawn()
+```
+
+**`SubmitCharacterAppearance()` persiste ET annonce, jamais l'un sans l'autre.**
+Persister sans annoncer laisserait le joueur seul à se voir changé ; annoncer
+sans persister le ferait repartir au visage par défaut au lancement suivant.
+
+L'apparence vit sur le **PlayerState** et pas sur le pawn : elle décrit le
+JOUEUR, pas le corps. Le pawn meurt et réapparaît, le PlayerState non —
+réapparaître avec le visage d'un autre n'aurait aucun sens, alors que perdre son
+inventaire au sol est la règle du jeu.
+
+**Rien n'est validé côté PlayerState, délibérément** : borner un index demande le
+catalogue, que seul le composant connaît — or il passe déjà tout ce qu'il monte
+par `Catalog->Sanitize()`, sur chaque machine.
+
+## 11. Le parcours de l'écran
+
+```
+clic Jouer → fondu au noir → SetViewTarget(BP_CharacterPreview)
+           → colonne affichée → fondu depuis le noir
+           ├─ « Jouer »  → apparence persistée → fondu de départ → GameScene
+           └─ « Retour » → fondu → nouvel angle de menu
+```
+
+On ne charge **aucune map** : le mannequin est posé dans `MenuScene`. La bascule
+de caméra se fait pendant que l'écran est noir — un travelling depuis l'angle du
+menu traverserait le décor.
+
+**L'écran part toujours de l'apparence par défaut**, jamais de la persistée.
+C'est un provisoire assumé : à terme l'apparence appartiendra à la **sauvegarde**
+et non au joueur, et l'on regardera au clic sur *Jouer* si cette partie a déjà un
+personnage. `SetupCustomization(Preview, Appearance)` prend déjà l'apparence en
+paramètre — il n'y aura qu'à changer son origine.
+
+Laisser **`Customization Menu Class` vide** sur `BP_MainMenuPlayerController`
+restaure l'ancien comportement (Jouer lance directement). Pratique pour tester
+autre chose sans traverser l'écran.
+
+## 12. Les pièges du moteur rencontrés
+
+Aucun n'était visible depuis le code. Ils sont ici pour ne pas être redécouverts.
+
+### Les `UFUNCTION(Exec)` d'un `UActorComponent` ne sont JAMAIS appelées
+
+La chaîne de routage (`UPlayer::Exec`, dans `Player.cpp`) interroge le monde, le
+`PlayerInput`, le contrôleur, le **pawn**, le HUD, le GameMode, le `CheatManager`,
+le GameState et le camera manager — **jamais les composants**, `AActor` ne
+surchargeant pas `ProcessConsoleExec` pour les parcourir. Et rien ne proteste :
+la commande est introuvable, sans message.
+
+D'où `EmberPart` / `EmberColor` / `EmberAppearanceDump` posées sur `AFpsPlayer`,
+qui délègue. *(`EmberJoin` marche parce que `UGameInstance`, lui, route vers ses
+subsystems.)*
+
+### `OverrideMaterials` survit à un changement de mesh
+
+`SetSkeletalMeshAsset` remplace l'asset mais ne touche pas au tableau
+`OverrideMaterials`, qui appartient au **composant**. Sans vidage préalable,
+passer du corps A au corps B garde le MID dérivé de `MI_BodyA_a` : on obtient une
+silhouette féminine peinte avec la peau et les abdominaux du modèle masculin.
+Le symptôme trompe, parce que le mesh, lui, a bien changé.
+
+D'où `SetPartMesh()`, qui appelle `EmptyOverrideMaterials()` avant d'assigner —
+et ne fait rien si le mesh est déjà le bon, pour que les MID survivent à un simple
+changement de couleur.
+
+### L'ordre des slots de matériau varie d'un mesh à l'autre
+
+Sur `SKM_HeadA_01`, l'**Element 0 est celui des YEUX** et l'Element 1 celui de la
+peau — l'inverse de l'intuition. Les six têtes viennent de deux packs différents,
+rien ne garantit qu'elles s'accordent.
+
+On cherche donc le slot **par son nom** (`EyeMaterialSlotHint`, valeur `Eye`), et
+si aucun ne correspond on ne pose rien et on l'écrit dans le log : écraser le slot
+de la peau repeint le visage entier de la couleur des yeux, symptôme bien plus
+long à diagnostiquer qu'une ligne de log.
+
+### Un nom de paramètre matériau se lit dans le Material INSTANCE
+
+Le binaire de `M_Head_Base` contient la chaîne « Skin Base color », mais le
+paramètre réellement exposé s'appelle **`Skin`**. Le chercher sous l'autre nom
+dans `MI_HeadA_01_a` ne rend aucun résultat.
+
+Corollaire : les noms de paramètres sont des `UPROPERTY` du catalogue et pas des
+constantes C++, pour qu'une erreur se corrige sans recompiler.
+
+### `LeaderPoseComponent` est `BlueprintReadOnly`
+
+Elle n'apparaît **jamais** dans le Details panel — la section « Leader Pose
+Component » qu'on y voit ne contient que des cases de bornes et de LOD. Elle ne
+s'assigne que par `SetLeaderPoseComponent()`, en C++ ou en Construction Script.
+
+### `Approx Size` d'un Skeletal Mesh n'est pas sa hauteur visible
+
+Les bounds incluent une marge et celles du Physics Asset. `SKM_BodyA` affiche 184
+alors que le personnage entier mesure à peu près autant. Pour juger une taille :
+viewport en vue **Front**, et la ligne verte (`Z = 0`) comme repère — le bas de la
+capsule est à `-HalfHeight`, le haut à `+HalfHeight`.
+
+### `Initialize` masque une virtuelle d'`UUserWidget`
+
+`UUserWidget::Initialize()` existe et est virtuelle. Une surcharge de signature
+différente la **masque** au lieu de la surcharger (C4263/C4264). D'où
+`SetupCustomization`. Même famille de piège que les membres nommés `Player` ou
+`Slot` dans une classe dérivée du moteur.
+
+## 13. Les commandes console
+
+Sur le pawn, en partie. Elles appliquent en local **et** soumettent (persistance
+ annonce au serveur), donc elles testent toute la chaîne.
+
+```
+EmberPart body 0..1          silhouette
+EmberPart head 0..5          visage
+EmberPart hair 0..12         coiffure
+EmberPart eyebrows 0..5      sourcils
+EmberPart beard 0..5         barbe
+EmberPart mustache 0..5      moustache
+EmberPart eyes 0..4          forme d'iris
+EmberPart beard -1           retire la pièce
+
+EmberColor skin 0..11        teint
+EmberColor hair 0..5         cheveux + barbe + sourcils + moustache
+EmberColor eye 0..4          iris
+EmberColor underwear 0..3    sous-vêtement
+
+EmberAppearanceDump          état courant + nombre d'options par catégorie
+```
+
+`EmberAppearanceDump` est le premier réflexe de diagnostic : un compte à **0**
+signale une liste vide dans le catalogue.
+
+## 14. Dépannage
+
+| Symptôme | Cause |
+|---|---|
+| La colonne de l'écran est vide | `Catalog`, `Category Widget Class` ou `Option Widget Class` non assignés dans les **Class Defaults** de `WBP_CharacterCustomization` (mode **Graph** → *Class Defaults*) |
+| *Jouer* lance la partie sans montrer l'écran | `Customization Menu Class` vide sur `BP_MainMenuPlayerController` |
+| Écran noir qui ne s'éclaircit pas | aucun `BP_CharacterPreview` dans la map — un avertissement l'écrit dans l'Output Log |
+| Le visage ne suit pas la couleur de peau | `Head Skin Color Parameter` faux dans le catalogue (`Skin`, pas `Skin Base color`) |
+| Le visage entier prend la couleur des yeux | `Eye Material Slot Hint` ne correspond à aucun slot — le log liste les slots disponibles |
+| Le corps B garde la peau du corps A | régression de `SetPartMesh()` : les overrides ne sont plus vidés |
+| Une pièce flotte détachée du corps | leader pose non posé sur ce composant |
+| Corps figé en pose de référence | `Anim Class` absente du Body Set |
+| Les pastilles de couleur sont invisibles | le pinceau d'`OptionImage` est en `Draw As = Image` sans texture — un pinceau en mode Image sans texture ne peint rien |
+| En PIE à 2, les deux joueurs sont identiques | normal : les deux fenêtres lisent le même `.ini`. Change l'un des deux à la console |
+
+## 15. Limites connues
+
+- **Les bras vus en 1re personne ne sont pas customisés.** Leur squelette
+  (`BasePose_Skeleton`) n'a rien à voir avec `SK_BodyA` ; les rendre
+  customisables imposerait de retargeter toutes les animations FPS. Raft assume
+  le même compromis.
+- **La physique de cheveux est perdue en leader pose.** Coiffures, barbes et
+  moustaches ont leur physics asset, mais l'AnimBP post-process d'un *follower*
+  ne tourne pas. La démo du pack accepte déjà ce compromis.
+- **Tatouages et maquillage ne sont pas exposés.** `M_Head_Base` et
+  `M_Body_Base` en ont pourtant les paramètres : ce ne sont que des couleurs et
+  des masques de plus à ajouter au catalogue, aucune refonte.
+- **Pas d'animation accroupie.** Le pack n'en livre pas. Mais le squelette est
+  celui du **Mannequin UE5** (`ik_foot_root`, `index_metacarpal_l`…), donc toute
+  animation vendue « UE5 Mannequin compatible » se branche **sans retarget**.
+
+## 16. Étendre
+
+**Ajouter une catégorie** (tatouages, maquillage) :
+
+1. un champ dans `FCharacterAppearance`
+2. une valeur dans `ECharacterPartCategory` (mesh) ou une palette (couleur)
+3. une valeur dans `ECustomizationCategory` + son libellé dans
+   `CharacterCustomizationLabels::Get`
+4. les branches correspondantes dans `GetOptionCountForCategory`,
+   `GetCurrentIndexForCategory` et `SetIndexForCategory`
+
+L'écran, lui, n'a rien à changer : la colonne se construit depuis l'enum.
+
+**Brancher les sauvegardes** : une seule ligne, dans
+`AMainMenuPlayerController::OpenCustomization()` — passer l'apparence de la save
+au lieu de `FCharacterAppearance()`.