Caffeine

7.7 — Colisão Física (Heightfield Collider)

Historical Fase: 13 · **Prioridade:** Alta (gameplay) · **Esforço:** Alto Last updated:
> **Depende de:** Fase 2 (chunks/LOD), sistema de física do engine > **Bloqueia:** Play mode com personagens no terreno

Objetivo#

Fornecer colisão física baseada no heightmap — personagens, objetos e raycasts respeitam o relevo do terreno em editor e runtime.


Abordagens#

Abordagem Prós Contras
Heightfield collider Preciso, padrão em engines Só funciona para "single heightmap", não overhangs
Mesh collider por chunk Funciona com qualquer mesh Mais pesado, precisa rebuild em sculpt
Simplified collision mesh Balanceado Implementação extra

Recomendado: Heightfield para terreno base + mesh collider opcional para rochas/objetos.


Heightfield Collider#

Dados#

cpp
struct TerrainColliderComponent {
    bool enabled = true;
    f32 worldSizeX = 64.0f;
    f32 worldSizeZ = 64.0f;
    f32 maxHeight = 16.0f;
    u32 resolutionX = 65;
    u32 resolutionZ = 65;
    // heights em world units, não normalizados
    // ou ponteiro para TerrainCache heightmap
};

API física (a definir conforme backend)#

cpp
// Se Jolt / Bullet / custom:
PhysicsWorld::createHeightfieldCollider(
    entity,
    heights.data(),
    resolutionX, resolutionZ,
    worldSizeX, worldSizeZ,
    maxHeight
);

Sincronização com TerrainCache#

text
TerrainCache::rebuildMesh() / rebuildRegion()
    → TerrainPhysicsSystem::syncCollider(entity)
        → atualizar heightfield ou flag "dirty"

Incremental#

Após sculpt em região:

cpp
physics->updateHeightfieldRegion(minX, minZ, maxX, maxZ, newHeights);

Requer backend que suporte patch de heightfield — senão rebuild completo.


Chunks + LOD#

Colisão deve usar resolução máxima do heightmap, não mesh LOD renderizada.

text
Render: chunk LOD 0–3 (simplificado)
Physics: heightmap full 65×65 ou 129×129

Para terrenos enormes (futuro streaming): collision por chunk com heightfield local.


Editor#

Inspector — Terrain#

text
[✓] Physics Collider
    Type: [Heightfield ▼]
    [Rebuild Collider]

Debug draw#

  • Wireframe overlay da collision mesh (toggle no viewport)
  • Cor distinta do chunk debug LOD

Runtime#

RuntimeSceneRenderer + PhysicsSystem precisam de:

  1. Carregar .cterrain no runtime
  2. Criar collider na inicialização da cena
  3. Atualizar se terreno mudar (improvável em runtime v1)

Gap atual: syncTerrainMeshes() só no editor — portar para runtime.


Ficheiros a Criar/Alterar#

text
src/ecs/TerrainComponents.hpp       // TerrainColliderComponent ou flag em TerrainComponent
src/scene/TerrainPhysicsSystem.hpp
src/scene/TerrainPhysicsSystem.cpp
src/physics/HeightfieldCollider.hpp  // wrapper backend
src/runtime/RuntimeSceneRenderer.cpp // sync terreno

Critérios de Aceitação#

  • [ ] Personagem/cápsula colide com superfície do terreno em play mode
  • [ ] Sculpt no editor atualiza colisão (full ou região)
  • [ ] Raycast downward encontra terreno corretamente
  • [ ] Performance: collider 65² sem frame drops
  • [ ] Sem collider duplicado ao duplicar entidade Terrain

Ordem de Implementação Interna#

  1. Auditar backend de física atual (PhysicsComponents2D existe — ver 3D)
  2. Protótipo heightfield estático num terreno flat
  3. Sync heights do TerrainCache
  4. Rebuild incremental após sculpt
  5. Runtime path

Referências#

  • Unity: TerrainCollider + TerrainData
  • Godot: HeightMapShape3D
  • Bevy: HeightfieldCollider via Rapier