bvle-voxels/plan_phase4.md

# Plan Phase 4 — Toping (meshes décoratifs adaptatifs)

Le toping consiste à placer automatiquement des **meshes 3D procéduraux** sur les faces exposées de certains voxels, qui s'adaptent à leur voisinage via un bitmask 4 bits (16 variantes). C'est fondamentalement différent des phases précédentes : on passe du rendu de quads au rendu de **triangles instanciés** avec géométrie 3D.

## Phase 4.1 — Infrastructure TopingSystem + génération de meshes procéduraux

**Objectif** : Créer le système de données (TopingDef, TopingInstance) et générer des meshes de test procéduralement (pas d'import d'assets).

- **`TopingSystem` class** (`src/voxel/TopingSystem.h/.cpp`) :
  - `TopingDef` : définit un type de toping (ID matériau source, face(s) applicables, 16 mesh variants indexées par bitmask d'adjacence)
  - `TopingInstance` : position monde (float3) + rotation/face + variant index + toping type ID
  - Registry de `TopingDef` (tableau fixe, 2-3 types de test)
  - Collecte des instances : itérer sur les voxels exposés d'un chunk, vérifier le matériau, calculer le bitmask 4 bits des voisins cardinaux dans le plan de la face, émettre un `TopingInstance`

- **Meshes procéduraux de test** (pas d'assets externes) :
  - **Type 1 — Rebord de pierre** : sur les faces +Y de la stone, petit biseau/corniche qui longe le bord supérieur
  - **Type 2 — Bordure d'herbe** : sur les faces +Y du grass, petites touffes/relief organique sur les bords
  - Chaque type a 16 variants (straight, corner, T-junction, cross, isolé, etc.) générées par code

- **Livrables** : TopingSystem peut scanner un chunk et produire une liste de TopingInstance. Pas de rendu encore.

## Phase 4.2 — GPU buffers + pipeline de rendu instancié

**Objectif** : Rendre les toping instances sur le même render target que les voxels.

- **Vertex buffer partagé** pour les mesh variants :
  - Toutes les variantes de tous les TopingDef dans un seul vertex buffer (position + normal + UV)
  - Index table : `meshOffset[topingType][variant]` → offset + vertex count dans le VB

- **Instance buffer** (`StructuredBuffer<TopingInstance>`) :
  - Rempli par le CPU après collecte (comme le mega quad buffer)
  - Contient : world position, face rotation matrix (ou quaternion), mesh variant offset

- **PSO toping** :
  - Nouveau VS (`voxelTopingVS.hlsl`) : lit instance data + vertex data, transforme en world space
  - Réutilise le PS existant (ou PS simplifié avec UVs classiques au lieu de triplanar)
  - Même root signature, même depth buffer, même render target
  - `DrawInstanced` ou `DrawInstancedIndirect` groupé par type de mesh

- **Intégration dans `VoxelRenderer::render()`** : après le draw des voxels, draw des topings dans le même render pass

## Phase 4.3 — Adjacence dynamique + optimisation

**Objectif** : Le bitmask s'adapte quand le monde change, et le pipeline est performant.

- **Recalcul incrémental** : quand un chunk est dirty, recalculer uniquement les toping instances de ce chunk + les chunks voisins (bords)
- **Frustum culling** : skip les instances hors frustum (par chunk, comme les voxels)
- **Benchmark** : mesurer le coût GPU pour 50K instances (cible < 2ms)
- **Mode debug** (F5 ?) : visualiser les bitmasks d'adjacence en couleur
- **Cross-chunk adjacency** : voisins aux frontières de chunks (comme le mesher fait déjà)

## Complexité estimée

Phase 4.1 est la plus lourde (design des structures + génération procédurale des 16 variants × 2 types). Phase 4.2 est mécanique (pipeline GPU classique). Phase 4.3 est de l'optimisation.

## Prérequis

Avant d'implémenter, une étude des systèmes de meshes connectés contextuels est nécessaire (WFC, dual grid, marching squares variants, etc.) — voir `research_connected_meshes.md`.