Caffeine

7.1 — Módulos Adicionais de Geração

Historical Fase: 7 · **Prioridade:** Alta · **Esforço:** Médio Last updated:
> **Depende de:** Fase 6 (pipeline `ITerrainGeneratorModule`) > **Bloqueia:** 7.2 (combinadores), 7.3 (brush)

Objetivo#

Expandir o pipeline modular com novos módulos que o utilizador pode combinar livremente (estilo Custom), além dos presets Realistic / Low Poly / Stylized.


Módulos a Implementar#

1. Domain Warp (módulo separado)#

Atualmente o domain warp está embutido em BaseNoiseModule. Extrair para módulo independente permite:

  • Aplicar warp depois de combinar múltiplas fontes de noise
  • Controlar warp apenas numa região (com máscara)
  • Desligar warp no preset sem alterar o noise base
cpp
class DomainWarpModule final : public ITerrainGeneratorModule {
    // Lê heightmap ou coordenadas, distorce sampling para módulo seguinte
    f32 strength;
    u32 seed;
};

Parâmetros expostos: domainWarpStrength, domainWarpSeed (ou reutilizar generation.seed)


2. Fault Lines (falhas geológicas)#

Simula falhas tectónicas — deslocamento abrupto de altura ao longo de uma linha.

text
Algoritmo simplificado:
1. Definir linha (ponto A → B) ou linha aleatória com seed
2. Para cada vértice, calcular distância perpendicular à linha
3. Se dist < faultWidth: height += displacement * falloff(dist)

Parâmetros:

Campo Tipo Default
faultEnabled bool false
faultAngle f32 45°
faultOffset f32 0.5 (posição normalizada)
faultWidth f32 0.05
faultDisplacement f32 0.15

3. Contour Cliffs (falésias por curva de nível)#

Cria margens afiadas em transições de altitude — útil para estilo stylized e terrenos com planícies + penhascos.

cpp
if (abs(height[x,z] - height[vizinho]) > cliffThreshold) {
    // Empurrar vértice para cima ou para baixo → borda vertical
    height = quantize(height, cliffSteps);
}

Parâmetros:

Campo Tipo Default
cliffEnabled bool false
cliffThreshold f32 0.08
cliffSharpness f32 0.5

Integração#

Ficheiros novos#

text
src/terrain/generation/
├── TerrainGeneratorModules.hpp   // declarações dos novos módulos
└── TerrainGeneratorModules.cpp   // implementação

Ordem no pipeline (proposta)#

text
BaseNoise → DomainWarp → FaultLines → ThermalErosion → HydraulicErosion
         → ContourCliffs → Smooth → HeightQuantize → StylizedCurve → AutoSplat

ECS — novos campos em TerrainGenerationSettings#

cpp
// Domain warp (já parcialmente existente — mover lógica)
bool domainWarpAsModule = true;

// Fault lines
bool faultEnabled = false;
f32 faultAngle = 45.0f;
f32 faultOffset = 0.5f;
f32 faultWidth = 0.05f;
f32 faultDisplacement = 0.15f;

// Contour cliffs
bool cliffEnabled = false;
f32 cliffThreshold = 0.08f;
f32 cliffSharpness = 0.5f;

Inspector#

  • Secção Modifiers dentro de Procedural Generation
  • Checkboxes + sliders por módulo
  • Preview em tempo real opcional (requer 7.4 Undo para ser seguro)

Critérios de Aceitação#

  • [ ] Domain warp funciona como módulo independente no pipeline Custom
  • [ ] Fault lines produzem deslocamento visível e determinístico (mesmo seed → mesmo resultado)
  • [ ] Contour cliffs criam bordas afiadas sem artefatos em mesh LOD
  • [ ] Parâmetros serializados no blob terrain v3
  • [ ] Presets Realistic/LowPoly/Stylized não quebram com novos campos (defaults seguros)

Testes Manuais#

  1. Criar terreno Custom, só BaseNoise → plano com colinas
  2. Ativar Domain Warp → formas mais orgânicas
  3. Ativar Fault Lines → descontinuidade linear visível
  4. Ativar Contour Cliffs → planícies com bordas verticais
  5. Generate Terrain → mesh rebuild sem erros, splat coerente