Physics 2D
O sistema de corpos rígidos 2D: broad phase por hash espacial, colisão AABB e círculo, resposta por impulso com atrito, layers, triggers e raycasts.
Visão Geral#
Um sistema de física 2D simples com dinâmica de corpos rígidos, colisão AABB e circular,
layers e uma resposta de colisão simples (restitution + friction). O caffeine-runtime
registra-o ao lado do event bus.
Âmbito intencional: cobre a maioria dos casos 2D. Para joints, CCD ou convex hulls, integra uma biblioteca dedicada (Box2D/Jolt) como gatilho de escala.
API#
namespace Caffeine::Physics2D {
struct PhysicsMaterial {
f32 friction = 0.5f;
f32 restitution = 0.3f;
static PhysicsMaterial ice();
static PhysicsMaterial rubber();
static PhysicsMaterial metal();
static PhysicsMaterial wood();
static PhysicsMaterial stone();
};
struct RigidBody2D {
f32 mass = 1.0f;
f32 restitution = 0.3f;
f32 friction = 0.5f;
f32 linearDamping = 0.0f;
bool isKinematic = false;
bool lockRotation = true;
bool isSleeping = false;
f32 sleepTimer = 0.0f;
f32 velocityX = 0.0f;
f32 velocityY = 0.0f;
};
struct Collider2D {
Vec2 size = { 1.0f, 1.0f };
Vec2 offset = { 0.0f, 0.0f };
f32 radius = 0.5f;
u32 layer = 0;
u32 layerMask = 0xFFFFFFFF;
ColliderShape shape = ColliderShape::AABB;
bool isStatic = false;
bool isTrigger = false;
bool isOneWay = false;
u8 debugColor[4] = { 80, 200, 255, 220 };
};
struct Rect2D { Vec2 position; Vec2 size; };
struct RaycastHit { ECS::Entity entity; Vec2 point; Vec2 normal; f32 distance; bool hit; };
struct CollisionManifold { Vec2 contactPoint; Vec2 normal; f32 penetration; };
class PhysicsSystem2D : public ECS::ISystem {
public:
explicit PhysicsSystem2D(Events::EventBus* eventBus = nullptr);
void onUpdate(ECS::World& world, f32 dt) override;
void setGravity(Vec2 gravity);
Vec2 gravity() const;
RaycastHit raycast(ECS::World& world, Vec2 origin, Vec2 dir, f32 maxDist,
u32 layerMask = 0xFFFFFFFF);
std::vector<ECS::Entity> overlapCircle(ECS::World& world, Vec2 center, f32 radius,
u32 layerMask = 0xFFFFFFFF);
std::vector<ECS::Entity> overlapAABB(ECS::World& world, Rect2D rect,
u32 layerMask = 0xFFFFFFFF);
void applyForce(ECS::Entity e, Vec2 force);
void applyImpulse(ECS::World& world, ECS::Entity e, Vec2 impulse);
void setKinematic(ECS::World& world, ECS::Entity e, bool kinematic);
void teleport(ECS::World& world, ECS::Entity e, Vec2 position);
const std::vector<CollisionManifold>& lastManifolds() const;
};
}
O applyForce é thread-safe (protegido por mutex) e acumula até ao próximo update; o
applyImpulse altera a velocidade do corpo imediatamente no passo seguinte.
Pipeline de física do frame#
1. Broad phase- grelha de hash espacial (
kGridCellSize = 128) sobre as AABBs dos colliders
- grelha de hash espacial (
2. Narrow phase- AABB vs AABB
- Círculo vs Círculo
- Círculo vs AABB
3. Resolver colisões- impulso a partir de restitution/friction/mass
- correcção posicional (Baumgarte 0.4, slop 0.01)
4. Integrarvel += (gravity + forces) * dtpos += vel * dt(Euler semi-implícito, 2 substeps)
5. Publicar eventosOnCollision2DeOnTrigger2DviaEventBus::publishDeferred
Exemplos de uso#
// ── Setup ─────────────────────────────────────────────────────
Caffeine::Physics2D::PhysicsSystem2D physics(&eventBus);
physics.setGravity({0, -500.0f}); // pixels/s²
// ... chamar physics.onUpdate(world, dt) uma vez por frame
// ── Entidade com física ───────────────────────────────────────
world.add<RigidBody2D>(player, {
.mass = 5.0f,
.restitution = 0.3f,
.friction = 0.8f
});
world.add<Collider2D>(player, {
.size = {30, 60},
.offset = {0, 0},
.isStatic = false,
.layer = 1 // player layer
});
// ── Plataforma estática ───────────────────────────────────────
world.add<Collider2D>(platform, {
.size = {200, 20},
.isStatic = true,
.layer = 0 // world layer
});
// ── Impulso de salto ──────────────────────────────────────────
if (input.justPressed(Action::Jump)) {
physics.applyImpulse(world, player, {0, 800.0f});
}
// ── Raycast para "há chão por baixo?" ─────────────────────────
auto hit = physics.raycast(world, playerPos, {0, -1}, 32.0f);
bool onGround = hit.hit;
// ── Overlap para uma área de ataque ───────────────────────────
Rect2D attackBox = { playerPos + Vec2{20, 0}, {40, 40} };
auto hits = physics.overlapAABB(world, attackBox);
for (auto& enemy : hits) {
world.add<TakeDamage>(enemy, { .amount = 25 });
}
Layers de colisão#
Layer 0 = World (plataformas, paredes)
Layer 1 = Player
Layer 2 = Enemy
Layer 3 = Projectile
Layer 4 = Trigger
Máscara: layerMask = (1<<0)|(1<<2) = colide com World E Enemy
Um par colide quando o layerMask de cada collider inclui o layer do outro.
Gatilhos de escalada#
Se o jogo precisar de:
- Rotação de corpos rígidos → integra Box2D ou Jolt Physics
- Joints/constraints → biblioteca dedicada
- CCD (evitar tunneling a alta velocidade) → biblioteca dedicada
Decisões de design#
| Decisão | Justificativa |
|---|---|
| Formas AABB/círculo simples | Cobre a maioria dos casos 2D sem complexidade |
| Euler semi-implícito | Estável e simples para platformers |
| Eventos de colisão via EventBus | A física não acopla Audio/FX |
Mutex no applyForce |
Forças podem ser enfileiradas de outras threads |
| Limiar de sleep | Corpos parados deixam de integrar |
Critérios de aceitação#
- [ ] 1K corpos rígidos a 60fps
- [ ] Passo de física < 3ms para 1K corpos
- [ ]
tsanlimpo —applyForcethread-safe - [x] Raycast devolve o hit correcto em todos os ângulos
- [x] Colisões publicam
OnCollision2Dcorrectamente
Dependências#
- Upstream: ECS Core, Event Bus, Math
- Downstream: Audio (reage a colisões), Spatial Partitioning
Referências#
architecture_specs.md— §13 Physics 2D../core/events.md— eventoOnCollision2D- Box2D/LiquidFun — referência para casos avançados