7.7 — Colisão Física (Heightfield Collider)
> **Depende de:** Fase 2 (chunks/LOD), sistema de física do engine > **Bloqueia:** Play mode com personagens no terrenoObjetivo#
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:
- Carregar
.cterrainno runtime - Criar collider na inicialização da cena
- 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#
- Auditar backend de física atual (
PhysicsComponents2Dexiste — ver 3D) - Protótipo heightfield estático num terreno flat
- Sync heights do
TerrainCache - Rebuild incremental após sculpt
- Runtime path
Referências#
- Unity:
TerrainCollider+TerrainData - Godot:
HeightMapShape3D - Bevy:
HeightfieldCollidervia Rapier