# 🏗️ Architecture du Projet — ProjectF

> **Ce document est la référence d'architecture du projet, destinée en priorité aux modèles d'IA (Claude, etc.) qui vont lire, modifier ou créer du contenu dans ce projet Unreal Engine.**
> Il doit permettre de comprendre **où se trouve chaque système, quel fichier est responsable de quoi, et où ajouter du nouveau contenu** — sans avoir à explorer tout le projet à chaque session.
>
> ⚠️ **Ce document doit rester à jour.** Voir la section [10. Maintenir ce document à jour](#10-maintenir-ce-document-à-jour) et le skill `maintain-architecture-doc`.

---

## 1. Vue d'ensemble du projet

### 1.1 Nature du projet

- **Moteur** : Unreal Engine **5.8**.
- **Aucun code C++** : il n'y a pas de dossier `Source/`. Tout le gameplay est écrit en **Blueprint visuel**, dans `Content/`.
- **Genre** : jeu de survie / extraction en vue 3e personne avec un **inventaire en grille façon "Escape from Tarkov"** (armure, sac à dos, armes, munitions, craft sur feu de camp/fonderie, générateurs, lecteurs de carte magnétique, coffres, PNJ pillables, véhicules).
- **Multijoueur** : le système d'inventaire est répliqué (RPC client/serveur visibles partout dans `Inventory_Player`, ex. `Request Switch Weapon SERVER`, `Disarm Request SERVER`). Le projet doit donc être pensé serveur-autoritaire pour tout ce qui touche à l'inventaire, aux stats et au combat.

### 1.2 Les grandes couches du projet

Le projet est construit par empilement de **trois grands blocs** de contenu, plus une couche d'outillage IA :

1. **Framework de personnage / locomotion ("Sandbox Character")** — `Content/Systems/Blueprints/`
   Basé sur le sample officiel Epic "Motion Matching" (plugins `Mover`, `MotionWarping`, `MotionTrajectory`, `Chooser`, `AnimationLocomotionLibrary`, `AnimationWarping`). Gère le mouvement, la caméra, le Motion Matching, le traversal (vault/mantle/climb), les modes de mouvement personnalisés. **Ce framework est en grande partie template/tiers** : n'y toucher qu'en connaissance de cause.

2. **Système d'inventaire AGIS** ("Advanced Grid Inventory System", asset marketplace) — `Content/Core/Coreinventory/`, `Content/Systems/Inventory/`, `Content/UI/Inventory_UI/`, `Content/Data/Inventory_Data/`.
   C'est le **cœur du gameplay** : inventaire en grille, équipement, craft, loot, sauvegarde. La quasi-totalité des systèmes de jeu ajoutés par l'équipe (stats, mort, sélection rapide d'équipement, interactables) se branchent sur ce système.

3. **Systèmes de jeu spécifiques au projet**, ajoutés par-dessus AGIS — `Content/Systems/Stats/`, `Content/Systems/Scent/`, `Content/Systems/Movable_Object/`, `Content/Systems/Door/`, `Content/PCG/`, `Content/Items/`, `Content/UI/Widgets/` (HUD, pause menu). C'est ici que la majorité des évolutions de gameplay futures doivent être ajoutées.

4. **Outillage IA** — plugins `VibeUE`, `EditorToolset`, `ModelContextProtocol`, `Terminal` (déclarés dans `ProjectF.uproject`) + `.mcp.json` à la racine. Ils exposent l'éditeur Unreal (Blueprints, Widgets, Input, PCG, Landscape, Niagara, etc.) à un serveur MCP local (`http://127.0.0.1:8000/mcp`) piloté par des agents Claude. **C'est le mécanisme par lequel un modèle d'IA lit/modifie ce projet** — voir la section [9. Notes pour les IA](#9-notes-pour-les-ia-pièges-connus-de-loutillage) pour les pièges connus.

En plus de cela, deux couches d'assets tiers volumineuses sont présentes mais **ne contiennent pas de logique de gameplay propre au projet** : le pack météo **UltraDynamicSky** (`Content/Systems/Weather/UltraDynamicSky/`) et diverses bibliothèques d'assets 3D Fab/Megascans/Quixel (`Content/Fab/`, `Content/Megaplant_Library/`, une bonne partie de `Content/Animations/` et `Content/Characters/`).

### 1.3 Dépendances principales entre systèmes

```
Character (Pawn, géré par le framework "Sandbox Character")
 │
 ├─ Composant Inventory_Player          (Content/Core/Coreinventory/Inventory_Player)
 │   └─ hérite de Inventory_Equipper    (équipement d'armes/objets)
 │       └─ hérite de Inventory__Main   (cœur générique AGIS : slots, containers, réseau)
 │
 │   Inventory_Player pilote/possède :
 │   ├─ WB_InventoryScreen (UI d'inventaire complète, créée à la demande)
 │   │   └─ WB_InventoryPart1 / WB_InventoryPart2
 │   │       └─ WB_EquipSlot → WB_Container → WB_InventorySlot → WB_Item
 │   ├─ WB_QuickSelect (roue de sélection rapide d'équipement, 4 slots)
 │   └─ Les Input Actions IA_*AGIS via l'IMC_AGIS_Character / IMC_AGIS_InventoryTab
 │
 ├─ Composant AC_Stats                  (Content/Systems/Stats/AC_Stats)
 │   └─ Vie, mort (OnDeath), Revive → déclenche WB_YouDied et le respawn du Character
 │
 ├─ Composants de mouvement            (Content/Systems/Movement/, Systems/Blueprints/MovementModes/)
 │   └─ AC_ClimbingComponent, AC_Cover, AC_TraversalLogic, AC_PreCMCTick, AC_VisualOverrideManager…
 │
 └─ Autres composants gameplay         (AC_ScentPoint, etc.)

Interactables (Content/Systems/Inventory/Interactables/*)
 └─ Implémentent BPI_Interactable, exposent un inventaire via un composant
    Inventory_Storage / Inventory_Vendor / Inventory_Crafting (mêmes bases AGIS que le joueur)
    → consultés par Inventory_Player lors d'une interaction (touche IA_InteractAGIS)

Données d'items (Content/Data/Inventory_Data/, Content/Items/)
 └─ DT_Items (DataTable), ItemDefaults / ItemInfo (structs), DD_Item (DataAsset par item)
    alimentent à la fois l'UI d'inventaire ET les Blueprints d'objets sous Content/Items/BP_Item_*
```

### 1.4 Conventions de nommage des assets

| Préfixe | Signification | Exemple |
|---|---|---|
| `BP_` | Blueprint d'acteur | `BP_Campfire`, `BP_Item_Helmet` |
| `WB_` / `WBP_` | Widget Blueprint (UMG) | `WB_InventoryScreen`, `WBP_PauseMenu` |
| `AC_` | ActorComponent | `AC_Stats`, `AC_ClimbingComponent` |
| `IA_` | Input Action (Enhanced Input) | `IA_InteractAGIS`, `IA_QuickSelectAGIS` |
| `IMC_` | Input Mapping Context | `IMC_AGIS_Character` |
| `E_` / `EM_` | Enum | `E_MovementMode`, `EM_Road_Type` |
| `S_` / `ST_` | Struct | `S_TraversalCheckInputs`, `ST_Weather_Zone_forecasts` |
| `M_` | Material | `M_Road`, `M_Campfire` |
| `MI_` | Material Instance | `MI_Black`, `MI_Bottle` |
| `SM_` | Static Mesh | `SM_Campfire`, `SM_RifleAdvanced` |
| `SKM_` | Skeletal Mesh | `SKM_BodyArmor` |
| `PA_` | Physics Asset | `PA_BodyArmor` |
| `T_` | Texture | `T_Helmet` |
| `RT_` | Render Target | `RT_InspectRenderer` |
| `DT_` | Data Table | `DT_Items` |
| `DD_` | Data Definition (DataAsset) | `DD_Item` |
| `ML_` | Macro Library (Blueprint) | `ML_InventoryMacros` |
| `SG_` | SaveGame | `SG_AGIS_UID`, `SG_AGIS_World` |
| `GM_` / `PC_` | GameMode / PlayerController | `GM_Sandbox`, `PC_Sandbox` |
| `CR_` | Control Rig | `CR_ClimbingGraphV2` |
| `ABP_` | Animation Blueprint | `ABP_GenericRetarget` |
| `AM_` | Anim Modifier / Anim Montage | `AM_ReloadHip` |
| `NS_` | Niagara System | `NS_Tornado` |
| `BPI_` | Blueprint Interface | `BPI_Interactable` |

Le suffixe `AGIS` sur beaucoup d'assets (`IA_InteractAGIS`, `WB_...AGIS`, fonctions "Target is Inventory Player") signale qu'ils appartiennent au **socle marketplace AGIS**, par opposition aux ajouts spécifiques au projet.

### 1.5 Conventions importantes à respecter

- **Ne jamais renommer/déplacer** les assets du socle AGIS (`Content/Core/Coreinventory/`, une bonne partie de `Content/Systems/Inventory/`, `Content/UI/Inventory_UI/Widgets/WB_Container|WB_EquipSlot|WB_InventorySlot|WB_Item`) sans nécessité — de nombreuses références internes au plugin marketplace en dépendent.
- **Nouveau système de gameplay** → créer un dossier dédié sous `Content/Systems/<NomDuSysteme>/`, à l'image de `Systems/Stats/`, `Systems/Scent/`, `Systems/Movable_Object/`.
- **Nouvel objet d'inventaire (item)** → suivre le patron existant dans `Content/Items/` : un Blueprint `BP_Item_<Nom>` (héritant de `_BP_ItemBase` ou d'une base spécialisée dans `Items/BaseBlueprints/`), ses assets (mesh/matériau/texture) dans un sous-dossier `Content/Items/<Nom>/` ou `Content/Items/Resources/<Nom>/`, et une entrée dans `DT_Items` / les DataAssets sous `Content/Data/Inventory_Data/DataAssets/`.
- **Nouvel Input Action lié à l'inventaire** → `Content/Systems/Inventory/Other/Inputs/Actions/`, mappé dans `IMC_AGIS_Character` ou `IMC_AGIS_InventoryTab`. **Input Action de déplacement/caméra générique** → `Content/Core/PlayerController/Input/`, mappé dans `IMC_Sandbox`.
- **Nouveau widget d'inventaire** → `Content/UI/Inventory_UI/Widgets/`. **Nouveau widget hors inventaire** (HUD, menus) → `Content/UI/Widgets/`.
- Le clavier cible est **AZERTY** ; privilégier des touches identiques physiquement sur QWERTY/AZERTY pour les nouveaux raccourcis (ex. `V`, `B`).
- Réplication réseau : toute action qui modifie l'état du jeu côté inventaire/stats doit suivre le patron `Request X SERVER` (Custom Event `...SERVER`, `Replicated From Client, Executes On Server`) déjà présent dans `Inventory_Player`.

---

## 2. Vue d'ensemble de l'arborescence racine

```text
ProjectF/
├── .gitattributes              → Règles Git (LFS, line-endings)
├── .gitignore                  → Exclut Binaries/, Intermediate/, Saved/, DerivedDataCache/, .vscode/…
├── .mcp.json                   → Déclare le serveur MCP "unreal-mcp" (http://127.0.0.1:8000/mcp) utilisé par les agents IA
├── ProjectF.uproject           → Fichier projet UE5.8 : liste des plugins activés (voir §1.2/§8)
├── README.md                   → Description minimale du projet
├── Architecture_Projet.md      → CE DOCUMENT
│
├── .claude/                    → Skills et configuration Claude Code pour ce projet
│   └── skills/
│       └── maintain-architecture-doc/SKILL.md   → Skill de maintenance de ce document (voir §10)
│
├── .codex/, .cursor/, .gemini/, .vscode/   → Configuration d'IDE / d'agents IA tiers (mcp.json, config.toml…)
│
├── Config/                     → Configuration moteur & jeu (voir détail §7)
├── Content/                    → Tous les assets du jeu (voir détail §3 à §6)
│
├── Binaries/, Intermediate/, Saved/, DerivedDataCache/   → Générés par l'éditeur, exclus de Git, jamais à éditer/documenter
```

### 2.1 ⚠️ Fichiers isolés directement à la racine de `Content/`

Quelques fichiers importants vivent directement sous `Content/`, hors de toute organisation par dossier — à connaître avant de chercher "où est le personnage" ou "où est le GameInstance" :

```text
Content/
├── SandboxCharacter_CMC.uasset   → ⭐ Le Blueprint du PERSONNAGE JOUEUR lui-même (Character/Pawn). Référencé par GM_Dev, GM_Sandbox, PC_Sandbox, Gamemode_AGIS, WB_InventoryScreen, WBP_PauseMenu, BP_Moveble_Object, BP_Simply_Door, AC_PreCMCTick, AC_ClimbingComponent et son propre Anim BP (Systems/Blueprints/SandboxCharacter_CMC_ABP). C'est le point d'entrée central de tout le gameplay.
├── BP_GameInstance.uasset        → GameInstance réellement utilisé par le projet (à ne pas confondre avec `Core/Coreinventory/GameInstance_AGIS`, la base du plugin — vérifier lequel des deux est configuré comme GameInstance par défaut avant de supposer que c'est l'un ou l'autre).
└── DT_DemoTags.uasset (+ .T3D)   → DataTable de tags, probablement un reste de test/démo. Aucune référence trouvée dans le projet au 2026-09-04 — candidate à la suppression, mais volontairement laissée en l'état (non confirmée inutile).
```


---

## 3. `Content/Core/` — Socle inventaire (AGIS) + Player Controller + Tick

Le cœur technique de l'inventaire et des entrées génériques du joueur.

```text
Content/Core/
├── Coreinventory/                        → Cœur du plugin AGIS (composants, données, sauvegarde)
│   ├── Inventory__Main.uasset            → ActorComponent BASE : logique générique de containers/slots, réplication réseau. Racine de la hiérarchie d'inventaire.
│   ├── Inventory_Equipper.uasset         → hérite de Inventory__Main : ajoute la logique d'équipement (armes/objets tenus en main)
│   ├── Inventory_Player.uasset           → hérite de Inventory_Equipper : composant d'inventaire du JOUEUR. Contient toute la logique spécifique projet ajoutée cette session (SelectQuickSlot, ToggleQuickEquip, GetQuickSlotItemInfo, graphe INPUTS avec tous les bindings Enhanced Input du joueur)
│   ├── Inventory_Storage.uasset          → Inventaire des containers de stockage (coffres, trunk, etc.)
│   ├── Inventory_Vendor.uasset           → Inventaire des PNJ vendeurs
│   ├── Inventory_Crafting.uasset         → Inventaire des stations de craft (campfire, smelter, générateur)
│   ├── BP_AttachmentHandler.uasset       → ActorComponent gérant les attachements sur les armes (silencieux, lampe, chargeur…)
│   ├── CombatComponent.uasset            → ActorComponent : logique de combat (tir, dégâts) liée aux armes AGIS
│   ├── BP_SM_DroppedMesh.uasset          → Acteur représentant un objet lâché au sol (mesh statique + interaction de ramassage)
│   ├── ItemMesh_STATIC.uasset / ItemMesh_Skeletal.uasset  → Acteurs générant le rendu 3D d'un item tenu/lâché (mesh statique ou squelettal)
│   ├── DD_Item.uasset                    → DataAsset décrivant un item (référencé par ItemDefaults)
│   ├── FL_AGIS.uasset                    → Function Library : fonctions statiques utilitaires du plugin AGIS
│   ├── ML_AGISDefaults.uasset            → Macro Library : macros par défaut du plugin
│   ├── ML_AGIS_UMG.uasset                → Macro Library : macros dédiées à l'UI (UMG)
│   ├── ML_InventoryMacros.uasset         → Macro Library : macros génériques d'inventaire
│   ├── GameInstance_AGIS.uasset          → GameInstance de base du plugin (état persistant entre les maps)
│   ├── Gamemode_AGIS.uasset              → GameMode de base du plugin (indépendant de GM_Sandbox, voir §4)
│   ├── PlayerController_AGIS.uasset      → PlayerController de base du plugin
│   └── SG_AGIS_UID.uasset / SG_AGIS_World.uasset  → SaveGame : compteur d'UID uniques / état persistant du monde (sauvegarde)
│
├── PlayerController/                     → Input générique du joueur (mouvement, caméra), indépendant de l'inventaire
│   ├── IA_InitiateClimb / IA_LeapFromClimb / IA_MovingClimb.uasset   → Input Actions liées à l'escalade
│   └── Input/
│       ├── IMC_Sandbox.uasset            → Input Mapping Context PRINCIPAL du personnage (mouvement, caméra, saut…)
│       └── IA_Move, IA_Look, IA_Jump, IA_Sprint, IA_Run, IA_Walk, IA_Crouch, IA_Prone, IA_Strafe,
│           IA_Aim, IA_Interact, IA_ESC, IA_NextPawn, IA_Traverse, IA_TeleportToTarget,
│           IA_SwimmingDeep, IA_TwinStick_AimDirection, IA_Move_WorldSpace, IA_Look_Gamepad,
│           IA_NextVisualOverride, IA_rool.uasset   → Input Actions individuelles mappées dans IMC_Sandbox
│
└── Tick/                                 → Système de gestion centralisée du Tick (perf)
    ├── BPI_TickManager.uasset            → Interface implémentée par les acteurs qui veulent être "tickés" par le manager
    ├── BP_TickManager.uasset             → Acteur central qui distribue les ticks (probablement à fréquence configurable)
    └── E_TickFrequency.uasset            → Enum des fréquences de tick disponibles
```

---

## 4. `Content/Systems/` — Systèmes de gameplay

### 4.1 `Systems/Inventory/` — Extension du socle AGIS pour ce projet

```text
Content/Systems/Inventory/
├── BP_Spawner.uasset                     → Acteur de spawn (probablement spawn d'items/loot en début de partie)
├── DT_Items.uasset                       → DataTable listant tous les items du jeu (clé pour créer/reconnaître un item)
│
├── Interactables/                        → Tout ce que le joueur peut "interagir" avec (touche IA_InteractAGIS)
│   ├── BP_EnemyPuppet.uasset             → PNJ/mannequin pillable
│   ├── BP_Vendor.uasset                  → PNJ vendeur (utilise Inventory_Vendor)
│   ├── CraftingInteractables/
│   │   ├── Campfire/BP_Campfire.uasset   → Station de cuisson/craft (feu de camp) + ses assets (mesh, matériaux)
│   │   └── Smelter/BP_Smelter.uasset     → Station de fonte de minerai + ses assets
│   ├── FuelGenerator/BP_Generator.uasset → Générateur électrique (consomme du carburant)
│   ├── KeycardReader/BP_KeycardReader.uasset → Lecteur de carte magnétique (déverrouillage)
│   ├── Other/BP_SimpleDoor.uasset        → Porte interactable simple
│   └── Storages/
│       ├── BP_StorageBox.uasset, BP_Trunk.uasset, BP_SphereStorage.uasset, _BP_StorageBase.uasset  → Coffres/contenants de stockage (héritent de _BP_StorageBase)
│       └── Deadbody/BP_Deadman.uasset    → Cadavre pillable
│
├── Interfaces/                           → Interfaces Blueprint (contrats partagés)
│   ├── BPI_Interactable.uasset           → Contrat pour tout objet interactible (implémenté par tous les Interactables ci-dessus)
│   ├── BPI_SlotWidgets.uasset            → Contrat pour les widgets de slot d'inventaire
│   ├── BPI_HoldableItem.uasset           → Contrat pour un item tenable en main
│   ├── BPI_WeaponAGIS.uasset             → Contrat pour les armes
│   ├── BPI_DamageFeedback.uasset         → Contrat de retour visuel/sonore lors de dégâts
│   └── BPI_GameInstance_AGIS.uasset      → Contrat exposé par le GameInstance côté AGIS
│
├── Other/                                → Assets d'appoint de l'inventaire
│   ├── Animations/                       → Animations liées aux armes/mains nues (Jog, Rifle, TurnInPlace, WALK) — clips Motion Matching (MM_*) et montages (AM_*)
│   ├── Fonts/                            → Polices utilisées par l'UI d'inventaire
│   ├── Inputs/
│   │   ├── Actions/                      → **Toutes** les Input Actions liées à l'inventaire (IA_*AGIS), y compris IA_QuickSelectAGIS et IA_QuickEquipAGIS (sélection rapide, ajoutées pour ce projet)
│   │   ├── IMC_AGIS_Character.uasset     → Mapping Context actif en jeu (personnage) : touches 1/2/3/4, F, V, B, etc.
│   │   └── IMC_AGIS_InventoryTab.uasset  → Mapping Context actif quand l'inventaire plein écran est ouvert
│   ├── InspectCapture/                   → Rendu d'inspection d'objet (RT_InspectRenderer + BP_InspectRenderer + M_Inspect)
│   └── Materials/                        → Matériaux génériques réutilisés par les items (MI_Black, MI_Red, M_Metal, M_Outline…)
│
└── Utilities/                            → Outils d'éditeur (Editor Utility Widgets) pour la création de containers/inventaires
    ├── EUW_ContainersCreator.uasset, EUW_WidgetToInventoryData.uasset
    └── Others/WB_ContainerSpecsUtility.uasset, WB_CreatorContainerUtility.uasset
```

### 4.2 `Systems/Blueprints/` — Framework de personnage / locomotion ("Sandbox Character")

Contenu très largement issu du sample Epic **Motion Matching** (plugins `Mover`, `MotionTrajectory`, `Chooser`, `AnimationLocomotionLibrary`). À traiter comme un framework tiers : préférer l'étendre plutôt que le réécrire.

```text
Content/Systems/Blueprints/
├── BPI_SandboxCharacter_Pawn.uasset      → Interface du Pawn joueur (point d'entrée du framework de locomotion)
├── BPI_SandboxCharacter_ABP.uasset       → Interface de l'Anim Blueprint du personnage
├── AC_TraversalLogic.uasset              → ActorComponent : logique de traversal (vault/mantle/climb contextuel)
├── AC_PreCMCTick.uasset                  → ActorComponent : logique exécutée avant le tick du mouvement (Mover/CMC)
├── AC_VisualOverrideManager.uasset       → ActorComponent : gestion des overrides visuels du personnage
├── GM_Sandbox.uasset / PC_Sandbox.uasset → GameMode / PlayerController du framework de locomotion (indépendants de Gamemode_AGIS/PlayerController_AGIS, voir §3)
│
├── Cameras/                              → Système de caméra (Camera Rigs modulaires)
│   ├── CameraAsset_SandboxCharacter, CameraDirector_SandboxCharacter, CHT_CameraRig
│   ├── E_CameraMode.uasset, E_CameraStyle.uasset
│   └── Rigs/CameraRig_* (Close/Medium/Far × Aim/Freecam/Strafe, CrouchOffset, CollisionOffset, TwinStick…)
│
├── MovementModes/                        → Modes de mouvement personnalisés (plugin Mover)
│   ├── BP_MovementMode_Walking / _Falling / _Slide
│   ├── BP_MovementTransition_ToSlide / _FromSlide
│   └── BP_ClimbingMode.uasset
│
├── ControlRigs/CR_Biped_FootPlacement.uasset   → Control Rig : placement des pieds (foot IK)
├── RetargetedCharacters/ABP_GenericRetarget.uasset  → Anim BP générique pour le retargeting
│
├── AnimModifiers/                        → Anim Modifiers (post-traitement de clips d'animation à l'import)
├── AnimNotifies/                         → Anim Notifies personnalisées (BP_AnimNotify_FoleyEvent*, BP_NotifyState_EarlyTransition/MontageBlendOut) + enums associés
│
├── Data/                                 → Structs/Enums/Curves partagés par tout le framework de locomotion
│   ├── E_Gait, E_Stance, E_MovementMode, E_MovementState, E_MovementDirection(Bias), E_RotationMode,
│   │   E_AnalogStickBehavior, E_ExperimentalStateMachineState, E_TraversalActionType
│   ├── S_CharacterPropertiesForAnimation / _ForCamera / _ForTraversal, S_BlendStackInputs,
│   │   S_MoverCustomInputs, S_PlayerInputState, S_TraversalCheckInputs/Result,
│   │   S_TraversalChooserInputs/Outputs, S_ChooserOutputs, S_MovementDirectionThresholds,
│   │   S_RotationOffsetCurveChooser_Inputs, S_DebugGraphLineProperties
│   ├── Curve_RotationOffset_* , Curve_StrafeSpeedMap, CHT_RotationOffsetCurve  → Curve Tables pilotant les offsets d'animation
│   └── BFL_HelpfulFunctions.uasset, BPI_InteractionTransform.uasset
│
├── SmartObjects/                         → Intégration du plugin SmartObject (points d'ancrage d'animation contextuelle)
│   ├── CHPA_SmartObject, AC_SmartObjectAnimation
│   └── SmartObjectAnimationPayload, SmartObjectSelectionInputs/Outputs
│
└── SandboxCharacter_CMC_ABP.uasset       → Anim Blueprint principal du personnage joueur (piloté par `/Game/SandboxCharacter_CMC`). Anciennement égaré dans un dossier `d/` mal nommé — déplacé ici (nettoyage du 2026-09-04).
```

### 4.3 Autres systèmes de gameplay (ajouts spécifiques au projet)

```text
Content/Systems/
├── Stats/
│   └── AC_Stats.uasset                   → ActorComponent ACTIF : gère la vie du personnage (Health), la mort (bIsDead, dispatcher OnDeath), Heal, Revive (voir §1.3). Ajouté cette session pour le système de mort/respawn.
│
├── Door/
│   ├── Garage_Door/BP_Garage_door.uasset → Porte de garage interactable
│   └── Simply_Door/BP_Simply_Door.uasset → Porte simple interactable
│
├── Movement/
│   ├── Climbing/AC_ClimbingComponent.uasset, CR_ClimbingGraphV2.uasset (Control Rig), CR_Mannequin_BasicFootIK.uasset, ClimbingMaterial.uasset
│   └── Cover/AC_Cover.uasset              → ActorComponent : système de couverture (cover system)
│
├── Scent/BP_ScentPoint.uasset            → Point émetteur d'odeur (probablement pour une IA de traque par l'odorat)
├── Movable_Object/BP_Moveble_Object.uasset → Objet physique déplaçable par le joueur
├── Interact_Interface.uasset             → Interface d'interaction générique (racine de Systems/, à distinguer de BPI_Interactable dans Inventory/Interfaces/)
│
└── Weather/
    ├── Tornado/BP_Tornado.uasset, NS_Tornado.uasset   → Tornade dynamique (acteur + système Niagara), spécifique au projet
    └── UltraDynamicSky/                  → 🧩 **Asset marketplace tiers complet** (~789 fichiers : Blueprints, matériaux, sons, textures de ciel/météo dynamique). Ne pas modifier directement ; utiliser ses points d'extension documentés par le plugin (Weather_Presets, Climate_Presets, Sky_Modifiers). Structure interne : Blueprints/ (Enum, Functions, Occlusion, Sky_Modifiers, Sound, System, Tools, Utilities, Weather_Effects, Widgets), Materials/, Meshes/, Particles/, Sound/, Textures/, Maps/ (map de démo du plugin).
```

---

## 5. `Content/Data/` — Structures de données globales

```text
Content/Data/
├── DataTable/DT_Season.uasset            → DataTable des saisons (météo)
│
├── Enums/
│   ├── E_CoverD.uasset, E_WeaponType.uasset
│   ├── Enums/E_BodyPart.uasset
│   └── Movement_enum/Weapon_Equip.uasset
│   (⚠️ à ne pas confondre avec Data/Inventory_Data/Enumerations/ ci-dessous — deux emplacements d'enums coexistent)
│
├── Structure/Weather/                    → Structs météo (ST_Season, ST_WeatherZoneState, ST_Weather_Zone_CurentWeather/forecasts/_Data, ST_Zone_Influance)
│
└── Inventory_Data/                       → Données du système d'inventaire AGIS
    ├── DataAssets/
    │   ├── AttachmentData/               → AttachmentData (base) + AttachmentData_AdvancedRifle, AttachmentData_Flashlight : configuration des attachements d'armes
    │   ├── ContainerGroupData/           → Un DataAsset par "groupe de containers" (Backpack BIG/SMALL, Box/Chest Storage, Vest_1/2, ExampleStorage…) : définit la mise en page des slots d'un contenant
    │   └── InventoryData/                → Un DataAsset par inventaire prédéfini (PlayerInventoryPart1/2, CardReader_Inventory, Generator_Inventory, Vehicle_Inventory)
    ├── Enumerations/                     → Enums spécifiques AGIS : EAnimOverlayState, EBallDirections, EFourDirections/ETwoDirections, EInteractionType, EItemActions, ENestingRules, EPrintType, EReloadType, EServerVerificationType, ESlotAppearance, EVendorBuyOption
    └── Structures/                       → Structs spécifiques AGIS
        ├── ItemDefaults.uasset           → Struct CENTRALE décrivant un item (Name, etc.) — lue par WB_Item et par la logique de sélection rapide (Inventory_Player)
        ├── ItemInfo, SlotInfo, SlotAddress, SlotAppearance, SubItemInfo, RandomSubItem
        ├── ContainerInfo, ContainerAppearance
        ├── AttachmentInfo, EquipSlot_KeySettings/_OwnContainersSettings/_TextureSettings/_TitleSettings
        ├── ClientWidgetData, CombinedTexturesInfo, TextureInfo
        ├── CraftingSlotRowInfo, DragSounds, DebugPrint, FindResult, InspectCameraInfo, InteractCosmetics, ItemActorInfo, MenuActions
        └── SaveStructures/SaveData_Player, SaveData_Storages, Savedata_ItemActor   → Structures de sauvegarde (non encore branchées à un vrai système de save, voir §1.3 du système de mort)
```

---

## 6. `Content/UI/` — Interfaces utilisateur

```text
Content/UI/
├── Inventory_UI/                         → TOUTE l'UI de l'inventaire (socle AGIS + ajouts projet)
│   ├── MaterialResources/                → Matériaux/Material Instances de fond des slots (MI_Background_*, M_RuntimeItemMaterial…)
│   └── Widgets/
│       ├── WB_Container.uasset           → Widget représentant un container (grille de slots) — contient SlotWidgets[]
│       ├── WB_EquipSlot.uasset           → Widget d'un slot d'équipement (arme/speed) — contient Container
│       ├── WB_InventorySlot.uasset       → Widget d'un slot individuel dans une grille — expose "ItemWidget On Slot"
│       ├── WB_Item.uasset                → Widget représentant un item posé dans un slot — expose "Item Defaults" (struct ItemDefaults)
│       │
│       ├── InventoryMenu/
│       │   ├── WB_InventoryScreen.uasset → Widget racine de l'inventaire plein écran (contient InventoryPart1/InventoryPart2)
│       │   ├── WB_InventoryPart1.uasset  → Contient les 4 slots d'équipement (EquipSlotWEAPON, EquipSlotWEAPON2, EquipSlotSpeed1, EquipSlotSpeed2) + autres slots d'équipement (casque, gilet, gants, sac à dos…)
│       │   └── WB_InventoryPart2.uasset  → Grille(s) d'inventaire principale(s)
│       │
│       ├── ItemActionsMenu/WB_ItemMenu.uasset, WB_GeneralButton.uasset   → Menu contextuel d'actions sur un item
│       │
│       ├── LootWidgets/                  → Fenêtres de pillage, une par type de source (Human, Storage, Vendor, Vehicle, Generator, KeycardReader) héritant de _WB_LootWidgetBASE ; LootingCrafting/ pour les stations de craft
│       │
│       ├── MovableWindows/               → Système de fenêtres déplaçables (_WB_Window_Base) : ItemInspect/ (inspection 3D d'un item), ItemInventory/ (fenêtre d'inventaire flottante), WB_TitleBar_Window (barre de titre commune)
│       │
│       └── Other/
│           ├── WB_QuickSelect.uasset     → 🆕 Roue de sélection rapide (4 slots : Arme1/Arme2/Speed1/Speed2 + "Aucun"). Résout seule son Inventory_Player propriétaire au Construct (GetOwningPlayerPawn → GetComponentByClass). Ouverte/fermée depuis Inventory_Player (touche V maintenue).
│           ├── WB_YouDied.uasset         → Écran "Vous êtes mort" (système de mort/respawn)
│           ├── WB_ActionScreen, WB_InteractScreen, WB_InteractBall, WB_PickupDisplay   → Feedback d'interaction/pickup au sol
│           ├── WB_CombatHUD, WB_DisplayHUD, WB_WeaponAmmoInfo   → HUD de combat/munitions
│           ├── WB_InventoryBackground, WB_ItemInfo, WB_SlotTitle   → Éléments visuels d'appoint
│           └── WidgetTextures/           → Icônes des slots d'équipement (T_EquipSlot_*) et textures d'UI diverses
│
├── TextureUI/M_CharacterUI.uasset, RT_CharacterView.uasset   → Rendu de la vue personnage dans l'UI (ex. écran d'inspection du personnage)
│
└── Widgets/                              → UI HORS inventaire
    ├── HUD/WB_HUD.uasset, WB_New_HUD.uasset, WB_New_InterfacePlayer.uasset
    ├── PauseMenu/WBP_PauseMenu.uasset, WBP_Options.uasset
    └── interaction/WB_Interact.uasset
```

---

## 7. `Content/Items/`, `Content/PCG/`, `Content/Maps/`, `Content/VFX/`, `Content/Prop/`

```text
Content/Items/                            → Objets ramassables/équipables du jeu
├── BaseBlueprints/
│   ├── _BP_ItemBase.uasset               → Blueprint BASE de tout item (racine de hiérarchie)
│   ├── BP_Item_HoldableBase.uasset       → Base des items tenables en main
│   ├── BP_Item_Armor_Base.uasset         → Base des items d'armure/équipement porté
│   └── BP_Item_Skeletal_Base.uasset      → Base des items avec mesh squelettal
│
├── BP_Item_AdvancedRifle / _Backpack_Camper / _Backpack_Sport / _BodyArmor / _Flashlight /
│   _Gloves / _Helmet / _KevlarVest / _LightVest / _Siren.uasset     → Blueprints d'items "portés" (racine d'Items/)
├── Attachments/BP_Item_MagazineBase, BP_Item_RifleFlashlight, BP_Item_Suppressor.uasset  → Attachements d'armes
├── ItemObjects/BPI_MergeableItemObject, ItemObject__BASE, ItemObject_ConsumableBASE, ItemObject_Magazine.uasset  → Objets "monde" associés aux items (empilables, consommables, munitions)
│
├── Ammo/, Weapon/ (Base_Bow, Base_knife), Tool/ (saucepan), Water/ (water_bottle),
│   Food/ (Red_Apple, meat, cooked_Meat, Burnt_Meat), Resource/ (Stick, Stone)
│   → Chaque sous-dossier contient les assets (mesh/matériau/texture/Thumbnail) d'un item ; les Blueprints correspondants sont soit à la racine d'Items/, soit dans Resources/
│
├── Resources/                            → Assets 3D (mesh/matériau/texture) groupés par équipement porté, + cas particuliers
│   ├── Backpack_Camper/, Backpack_Sport/, BodyArmor/, Gloves/, Helmet/, KevlarVest/, LightVest/, Rifle/
│   ├── _Others/                          → Assets des petits objets (Keycard, Log, Meat, AmmoBox, Battery, Flashlight, FuelCanister, GoldIngot/GoldOre, Headphone, MoneyBag, WaterBottle)
│   └── ABP_SkeletalEquippables.uasset    → Anim Blueprint partagé par les items squelettaux équipés
│
└── ItemTextures/                         → Textures d'icônes/inventaire communes à tous les items (T_*)

Content/PCG/                              → Génération procédurale de contenu (plugin PCG)
├── Road/
│   ├── PCG_Road.uasset                   → Graphe PCG générant la route procédurale (matériaux vieillis/mousse/humidité, potholes via GeometryScript)
│   ├── BP_AbandonedRoad.uasset           → Acteur portant le graphe PCG
│   ├── M_Road.uasset, ST_Road_data.uasset, EM_Road_Type.uasset   → Matériau, struct de données et enum de types de route
├── Vegetation/TreeTest.uasset            → Graphe PCG de placement de végétation (arbres, générés via PVE pour la route)
└── test/NewPCGGraph1.uasset              → Graphe de test/brouillon

Content/Maps/DevMap/
├── MapDev1.umap                          → 🗺️ Map de développement PRINCIPALE (GameDefaultMap / EditorStartupMap, voir Config/DefaultEngine.ini)
├── GM_Dev.uasset                         → GameMode utilisé sur MapDev1 (hérite directement de GameModeBase, indépendant de GM_Sandbox/Gamemode_AGIS)
├── pcg_Test_Dev.umap                     → Map de test PCG
└── PCG_Test_Dev_HLODLayer_*, Untitled_HLOD0_Instancing.uasset   → Assets HLOD générés pour les maps de test

Content/VFX/
├── Firetrail/BP_FireTrail.uasset, Effects/P_BulletTrail.uasset, Materials/M_BulletTrail.uasset   → Traînée de balle
└── MI_MuzzleFlash, M_MuzzleFlash, MuzzleFlash, P_MuzzleFlash   → Effet de tir (bouche de canon)
├── M_Blood.uasset, T_Blood.uasset        → Effet de sang
└── crosshair.uasset, hitmarker.uasset    → Éléments de HUD de tir

Content/Prop/Wooden_Door/                 → Prop de porte en bois (mesh + matériaux), utilisé par les BP de porte interactable
```

---

## 8. Assets tiers / bibliothèques (peu ou pas de logique de gameplay)

Ces dossiers contiennent des assets achetés/importés (Marketplace, Fab/Quixel Megascans, Megaplant, packs d'animation mocap). Ils sont volumineux (des centaines de fichiers) et **ne sont volontairement pas détaillés fichier par fichier** ici — voir §10 pour la règle sur quand les documenter.

```text
Content/Animations/          → Clips de mocap tiers : DeerAndDoe/, Fox/, Wolf/, humain/ (Armed_mov, Avoid, Carrying, Cover,
                                Effect_Animation, INteraction, Prone, Push, SwimmingAnimation…)
Content/Characters/          → Meshes/matériaux/textures des personnages et animaux (Animal/DeerStagAndDoe|Fox|Wolf,
                                UEFN_Mannequin/ avec ses données de Motion Matching : AimOffset, Crouch, Idle, Jump,
                                MotionMatchingData/ [Channels, Databases, Normalization_Sets, Schemas], Poses, Run, Slide,
                                Sprint, Traversal, Walk, Rigs, Materials, Meshes, Textures)
Content/Fab/                 → Assets Fab/Quixel Megascans : MaterialFunctions/, MaterialParameterCollection/, Materials/
                                (Standard/VT), Megascans/Plants/ (Common_Hemp_Nettle, Wild_Grass ×2), Megascans/Surfaces/
                                (Damaged_Asphalt, Dirt_Ground, Forest_Floor), Textures/ (Standard/VT)
Content/Megaplant_Library/   → Végétation Megaplant : Plant_Bilberry/, Tree_European_Aspen/, Tree_Hornbeam/
                                (chacun avec Instances/, Materials/, Textures/)
Content/Thumbnails/          → Miniatures générées pour la Content Browser
Content/Collections/         → Collections d'assets (vide actuellement)
Content/Developers/catry/    → Dossier de développeur personnel (playground, Collections/) — non partagé/gameplay
Content/Misc/                → SandboxAnimCurveCompressionSettings.uasset (réglages de compression d'anim)
Content/__ExternalActors__/  → ⚙️ Généré automatiquement par World Partition (données par-acteur des maps, ex. LocomotionAnimPack).
Content/__ExternalObjects__/ → ⚙️ Généré automatiquement par World Partition (objets externes liés aux maps).
                                → Ces deux derniers dossiers ne doivent JAMAIS être édités ou documentés à la main :
                                  leur contenu suit automatiquement les maps et les acteurs qu'elles contiennent.
```

---

## 9. Notes pour les IA : pièges connus de l'outillage

Ce projet est modifié via le plugin **VibeUE** (service MCP `unreal-mcp`, voir `.mcp.json`), qui expose des services Python (`unreal.BlueprintService`, `unreal.WidgetService`, `unreal.InputService`, `unreal.EnumStructService`, etc.) pour piloter l'éditeur Unreal sans l'ouvrir manuellement. Quelques pièges rencontrés et leurs solutions :

- **`build_graph`** attend un champ **`"ref"`** pour identifier chaque nœud dans la liste `nodes` (pas `"id"`). Un mauvais nom de champ échoue silencieusement (retourne `None` sans erreur explicite).
- Les **variables locales à une fonction** (paramètres, locals créés via `add_object_variable` avec `graph=...`) ne sont pas fiables avec `build_graph`'s `variable_get`/`variable_set` : préférer des **variables membres** du Blueprint.
- Un `K2Node_VariableSet`/`Get` créé via un spawner_key générique (`discover_nodes` + `create_node_by_key`) peut se résoudre sur la **mauvaise classe** si plusieurs Blueprints chargés ont une variable de même nom affiché (ex. "Owner Inventory" existe à la fois sur `WB_Container` et sur un widget créé cette session) — toujours vérifier les pins du nœud créé (`get_node_pins`) avant de câbler, ou utiliser `build_graph` avec `type: "variable_set"` + `params.variable` en contexte "self" qui est fiable.
- Appeler une fonction Blueprint **préexistante** (créée dans une session antérieure/par le plugin marketplace) sur un **autre** Blueprint peut échouer silencieusement selon la méthode utilisée. Privilégier l'accès direct aux propriétés (`member_get`, fiable) plutôt que l'appel de fonction cross-Blueprint quand c'est possible ; sinon tester `add_function_call_on_variable` et vérifier le résultat via `get_node_pins`/`get_nodes_in_graph`.
- Écrire une valeur littérale sur un pin de type `Text`, `Object` ou `Class` via `set_node_pin_value` échoue souvent **silencieusement à l'affichage** (`get_node_pins` renvoie toujours `default_value: ""`) même quand l'assignation a réellement fonctionné — vérifier via une **compilation** (erreurs de compilation manquantes = probablement OK) plutôt que via une relecture du pin.
- **Toujours compiler ET sauvegarder** un Blueprint après modification (`BlueprintEditorLibrary.compile_blueprint` + `EditorAssetLibrary.save_loaded_asset`), puis **tester en PIE** et lire les logs (`EditorToolset.LogsToolset.GetLogEntries`, filtrer sur `"Blueprint Runtime Error"`) pour détecter les erreurs à l'exécution qu'une compilation réussie ne révèle pas (ex. accès à un élément de tableau hors limites).
- Le clavier cible du jeu est **AZERTY** : vérifier les mappings de touches existants (`IMC_Sandbox`, `IMC_AGIS_Character`, `IMC_AGIS_InventoryTab`) avant d'assigner une nouvelle touche, et choisir des touches physiquement identiques entre QWERTY/AZERTY.

---

## 10. Maintenir ce document à jour

Ce document **doit toujours refléter l'état réel du projet**. Un skill dédié — **`maintain-architecture-doc`** (`.claude/skills/maintain-architecture-doc/SKILL.md`) — rappelle systématiquement aux modèles d'IA de :

1. Consulter ce document avant de modifier la structure du projet.
2. Le mettre à jour après toute création/suppression/déplacement/renommage de fichier ou dossier important.
3. Ajouter une description pour tout nouveau fichier important.
4. Retirer les entrées obsolètes (fichiers supprimés).
5. Corriger les chemins après un déplacement.
6. Mettre à jour les descriptions quand un système évolue significativement.
7. Vérifier périodiquement la cohérence entre ce document et l'arborescence réelle.
8. Ne jamais laisser ce document dans un état sciemment obsolète après une modification de structure.

**Règle de detail** : un fichier "important" à documenter est un Blueprint/Widget/Data Asset/Struct/Enum/Input Action qui porte de la **logique ou des données de gameplay**. Les assets purement artistiques individuels (textures, meshes, clips d'animation, miniatures) n'ont pas besoin d'entrée dédiée — il suffit que leur **dossier parent** soit listé et décrit (cf. §8).

*Historique de nettoyage :*
- *2026-09-04 : `Content/Systems/Blueprints/d/SandboxCharacter_CMC_ABP` renommé/déplacé vers `Content/Systems/Blueprints/SandboxCharacter_CMC_ABP` via l'outil de renommage Unreal (les 7 références ont été recâblées automatiquement, compilation vérifiée OK).*
- *2026-09-04 : suppression de 8 redirecteurs Unreal morts (résidus de renommages passés, 0 référence chacun, confirmés sans danger) : `Content/Systems/Stats/ACStats.uasset`, `Content/Systems/Movement/BPC_ClimbingComponent.uasset`, `Content/Systems/Movement/ClimbingMaterial.uasset`, `Content/Systems/Movement/CR_ClimbingGraphV2.uasset`, `Content/Systems/Movement/CR_Mannequin_BasicFootIK.uasset`, `Content/BP_TickManager.uasset`, `Content/dqs.uasset`, `Content/E_WeaponType.uasset`. Les vraies versions de ces assets restent à `Content/Systems/Movement/Climbing/`, `Content/Core/Tick/BP_TickManager` et `Content/Data/Enums/E_WeaponType`.*

*Point de nettoyage identifié mais volontairement non traité : `Content/DT_DemoTags.uasset` (+ `.T3D`) — aucune référence trouvée, semble être un reste de test, laissée en l'état à la demande de l'utilisateur (voir §2.1).*