Box3D 딥다이브
— Box2D를 만든 사람이 20년 만에 내놓은 3D 게임 물리 엔진

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 딱 한 문장이다: "Box3D is a 3D physics engine for games." 하지만 이 담백한 한 줄 뒤에는 중요한 맥락이 있다. 저자 Erin Catto는 2007년부터 Box2D를 만들어 온 사람으로, Box2D는 앵그리버드류 물리 퍼즐부터 수많은 인디·상용 게임 엔진의 2D 물리 기반이 된 업계 표준급 오픈소스다. 그가 오랜 GDC(게임 개발자 컨퍼런스) 강연과 연구로 다듬은 물리 솔버 기법을 이제 3차원으로 확장한 것이 Box3D다.

실제로 저장소를 뜯어보면, 이것은 "장난감 예제"가 아니라 87개의 C 소스 파일로 이루어진 본격 엔진이다. 충돌 감지(broad/narrow phase), 강체 솔버, 8종의 관절(joint), 볼록 껍질(convex hull)·캡슐·구·삼각형 메시·높이 필드 충돌, 광선/도형 캐스트, 센서, 캐릭터 무버, 그리고 녹화·재생(recording/replay)과 크로스플랫폼 결정론까지 들어 있다. 핵심 라이브러리(box3d::box3d)는 C 런타임 외에 어떤 외부 라이브러리에도 의존하지 않는다 — 게임 엔진에 그대로 끼워 넣기 좋다는 뜻이다.

2왜 주목받는가

Box2D 창시자의 3D 후속작 · 갓 나온 v0.1.0 · "Soft Step" 솔버 · 결정론 · 무의존성 C17.

Box3D가 공개 직후 TrendShift 상위권에 오른 이유는 단순한 "새 물리 엔진"이어서가 아니다. Erin Catto라는 이름값과, 그가 십수 년간 발표해 온 솔버 연구가 마침내 3D로 결실을 맺었다는 서사 때문이다. 최초 릴리스 v0.1.0이 2026-06-30에 올라왔다 — 즉 이 문서를 쓰는 시점 기준 갓 며칠 된 따끈한 알파 소프트웨어다.

경쟁 3D 물리 엔진과 무엇이 다른가

3기술 스택 전체 지도

C17 코어 라이브러리 + C++20 샘플 앱 + CMake 빌드 + SIMD + 크로스플랫폼 그래픽/디버깅 도구.

Box3D는 "엔진 코어"와 "그것을 눈으로 보여 주는 샘플 앱"을 명확히 분리한다. 코어는 그래픽이 전혀 없는 순수 계산 라이브러리이고, 샘플 앱은 그 결과를 3D로 그려 주는 별도 프로그램이다. 이 분리 덕분에 코어는 어떤 렌더러(Unity·Unreal·자작 엔진)에도 붙일 수 있다.

4아키텍처 심화 분석

한 번의 b3World_Step 안에서 벌어지는 일 — 브로드페이즈 → 내로우페이즈 → 제약 그래프 → Soft Step 솔버 → 적분.

물리 엔진의 심장은 b3World_Step(worldId, timeStep, subStepCount) 함수 하나다. 게임이 매 프레임 이 함수를 부르면, 엔진은 "지난 1/60초 동안 세계가 어떻게 변했는가"를 통째로 계산한다. 그 내부는 대략 이런 파이프라인으로 흐른다.

① 브로드페이즈 — "부딪힐 리 없는 쌍"을 먼저 걸러낸다

물체가 n개면 충돌 검사 조합은 순진하게 하면 n²이다. 1,000개면 50만 번. 이걸 피하려고 dynamic_tree.c(무려 54KB)가 AABB 트리(각 물체를 감싸는 축 정렬 상자를 계층 트리로 관리)를 유지한다. 두 물체의 감싸는 상자조차 안 겹치면 정밀 검사를 아예 건너뛴다. 이 단계에서 살아남은 소수의 "충돌 후보 쌍"만 다음 단계로 넘어간다.

② 내로우페이즈 — GJK로 정밀 접촉을 계산한다

후보 쌍이 정해지면 실제로 얼마나, 어디서 겹치는지 계산한다. 볼록 도형 사이 거리는 distance.c(47KB)의 GJK 알고리즘이 담당하고, 겹침이 확인되면 convex_manifold.c(50KB)·triangle_manifold.c·mesh_contact.c 등이 접촉 매니폴드(접촉점 좌표 + 파고든 깊이 + 밀어낼 법선 방향)를 만든다. 도형 종류별(구·캡슐·볼록껍질·삼각형 메시·높이 필드) 전용 코드가 나뉘어 있다.

③ 제약 그래프 색칠 — 락 없이 병렬로 푸는 비결

여러 스레드가 동시에 물리를 풀 때 위험한 건, 두 스레드가 같은 물체를 동시에 수정하는 경우다(데이터 레이스). constraint_graph.c는 이를 그래프 색칠(graph coloring)로 막는다. 접촉·관절을 노드로 보고, "같은 물체를 공유하는 제약끼리는 다른 색"이 되도록 칠한다. 그러면 같은 색 그룹 안의 제약들은 절대 같은 물체를 건드리지 않으므로, 스레드들이 락 없이 병렬로 처리해도 안전하다. 색깔을 하나씩 순서대로 처리하되, 각 색 안에서는 마음껏 병렬화하는 것이다.

④ 솔버: "Soft Step" — 딱딱한 벽을 아주 강한 스프링처럼

이 엔진의 이름값 있는 부분이다. 전통적 솔버는 "물체가 절대 겹치면 안 된다"는 딱딱한(hard) 제약을 강제하다가 펄쩍 튀거나 부들부들 떠는(jitter) 불안정을 겪곤 한다. Erin Catto가 GDC 강연들에서 다듬어 온 Soft Step(소프트 제약) 접근은, 제약을 "아주 뻣뻣하지만 감쇠가 있는 스프링"으로 모델링해 수치적으로 훨씬 안정적으로 만든다. 그리고 한 스텝(1/60초)을 subStepCount(기본 4)개의 서브스텝으로 잘게 나눠 반복한다 — 60Hz 겉보기로 돌리되 내부적으로는 240Hz로 제약을 여러 번 다잡는 셈이다.

// docs/hello.md 원문 — 서브스텝의 의미를 저자가 직접 설명
float timeStep = 1.0f / 60.0f;   // 프레임레이트에 묶지 말 것 (고정 스텝 권장)
int   subStepCount = 4;          // 4로 나누면 제약이 240Hz로 풀림
b3World_Step(worldId, timeStep, subStepCount);  // 매 틱 1회 호출
// "More sub-steps improve accuracy at the cost of performance."

⑤ 아일랜드 & 잠재우기 — 멈춘 물체는 계산하지 않는다

서로 접촉·관절로 연결된 물체 무리를 아일랜드(island)라 부른다(island.c). 한 아일랜드의 모든 물체가 충분히 오래 거의 안 움직이면, 엔진은 그 무리를 "잠재워(sleep)" 다음 스텝부터 계산에서 빼 버린다. 바닥에 쌓여 정지한 상자 100개를 매 프레임 다시 푸는 건 낭비이기 때문이다. 새 충돌이 들어오면 그 아일랜드만 다시 깨운다. 이것이 "많은 물체 더미에 최적화"의 핵심 비결 중 하나다.

⑥ 결정론 & 녹화·재생 — 어디서 돌려도 똑같은 결과

Box3D는 크로스플랫폼 결정론을 설계 목표로 못 박았다. 같은 입력을 주면 Windows·Linux·macOS에서 비트 단위로 동일한 시뮬레이션 결과가 나오도록 하는 것이다. 이를 위해 CMake에서 -ffp-contract=off(부동소수점 곱셈-덧셈 융합 최적화 차단)를 켜 컴파일러가 결과를 미묘하게 바꾸는 걸 막는다. 그 위에 recording_replay.c(116KB)·world_snapshot.c가 얹혀, 시뮬레이션을 녹화했다가 나중에 똑같이 재생할 수 있다.

5디렉토리 구조 해부

최상위 레이아웃 + src/ 87개 소스 파일을 역할별로 묶어서.

진짜 알맹이인 src/의 87개 파일을 역할별로 묶으면 물리 엔진의 해부도가 보인다.

6학습 포인트 (기술별)

이 저장소에서 실제로 무엇을 배울 수 있는가 + 각 주제 실습 아이디어.

7하드웨어 / 시스템 요구사항

코어를 빌드하려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 빌드하고, 굴려 보고, 붙여 쓰고, 뜯어보기.

과제 1 · Hello Box3D 돌려보기 난이도 ★☆☆☆☆

공식 docs/hello.md의 최소 예제를 그대로 따라 해 본다. 그래픽 없이 콘솔에 상자가 y=4에서 떨어져 y≈1에 멈추는 좌표가 찍힌다. 물리 엔진 사용의 전체 뼈대(세계 생성 → 물체·도형 붙이기 → 스텝 루프 → 정리)를 30줄로 체득하는 것이 목표.

// 핵심 골격 (docs/hello.md 요약, C)
#include <box3d/box3d.h>
#include <stdio.h>

int main(void) {
    b3WorldDef worldDef = b3DefaultWorldDef();      // 기본값 채우기
    worldDef.gravity = (b3Vec3){ 0.0f, -10.0f, 0.0f };
    b3WorldId world = b3CreateWorld(&worldDef);

    // 바닥(정적 물체)
    b3BodyDef groundDef = b3DefaultBodyDef();
    groundDef.position = (b3Vec3){ 0.0f, -10.0f, 0.0f };
    b3BodyId ground = b3CreateBody(world, &groundDef);
    b3BoxHull groundBox = b3MakeBoxHull(50.0f, 10.0f, 50.0f);   // 절반 크기(half-extent)
    b3ShapeDef gsd = b3DefaultShapeDef();
    b3CreateHullShape(ground, &gsd, &groundBox.base);

    // 떨어지는 상자(동적 물체)
    b3BodyDef boxDef = b3DefaultBodyDef();
    boxDef.type = b3_dynamicBody;                   // 안 켜면 안 떨어진다!
    boxDef.position = (b3Vec3){ 0.0f, 4.0f, 0.0f };
    b3BodyId body = b3CreateBody(world, &boxDef);
    b3BoxHull cube = b3MakeCubeHull(1.0f);
    b3ShapeDef sd = b3DefaultShapeDef();
    sd.density = 1.0f; sd.baseMaterial.friction = 0.3f;   // 밀도 0이면 안 됨
    b3CreateHullShape(body, &sd, &cube.base);

    for (int i = 0; i < 90; ++i) {
        b3World_Step(world, 1.0f/60.0f, 4);          // dt, 서브스텝 4
        b3Vec3 p = b3Body_GetPosition(body);
        printf("%4.2f %4.2f %4.2f\n", p.x, p.y, p.z);
    }
    b3DestroyWorld(world);                           // 전부 한 번에 해제
    return 0;
}

과제 2 · 프리셋으로 샘플 앱 빌드·실행 난이도 ★★☆☆☆

CMake 프리셋으로 실제 3D 샘플을 띄워 본다. imgui 패널로 데모를 바꿔 가며 물리 거동을 눈으로 관찰하는 것이 목표.

# 리눅스 예시 (README 기준)
cmake --preset linux-release
cmake --build --preset linux-release
./build/bin/samples
# Windows: cmake --preset windows → build_vs2026.bat 도 가능
# macOS:   cmake --preset macos

과제 3 · 관절(joint)로 진자·자동차 만들기 난이도 ★★★☆☆

과제 1 코드에 revolute joint(경첩)로 진자를, wheel joint로 간단한 서스펜션 자동차를 붙여 본다. include/box3d/box3d.h의 관절 API와 samples/의 관절 데모를 참고하면 된다. 관절 8종의 차이를 직접 손으로 익히는 것이 목표.

과제 4 · 내 프로젝트에 FetchContent로 통합 난이도 ★★★☆☆

README가 권장하는 방식으로, 빈 CMake 프로젝트를 만들고 Box3D를 FetchContent로 끌어와 링크해 본다. "무의존 코어를 남의 프로젝트에 끼우는" 실전 경험이다.

include(FetchContent)
FetchContent_Declare(box3d
  GIT_REPOSITORY https://github.com/erincatto/box3d.git
  GIT_TAG v0.1.0)
FetchContent_MakeAvailable(box3d)
target_link_libraries(my_app PRIVATE box3d::box3d)

과제 5 · 내부 뜯어보기 — 잠재우기(sleep) 관찰 난이도 ★★★★★

상자 수백 개를 쌓아 놓고, 정지 후 어느 시점에 아일랜드가 "잠드는지"를 island.c에 로그를 심어 관찰한다. 나아가 BOX3D_PROFILE(Tracy)을 켜 잠든 물체가 스텝 시간에서 빠지는 걸 프로파일러로 확인한다. 엔진 최적화의 핵심을 코드 레벨에서 이해하는 것이 목표.

9관련 기술 심화 학습 로드맵

물리 엔진을 "쓰는 사람"에서 "이해하는 사람"으로 — 6주 계획.

10핵심 키워드 사전

이 문서와 저장소에 나온 주요 용어 정리.

11참고 링크

공식 저장소 · 문서 · 저자 자료.