birds.cafe 딥다이브
— 번들러 없는 순수 Three.js로 만든 '바다 위 갈매기 비행' WebGL 힐링 시뮬레이터

kanavtwtgg/birds.cafe. 브라우저에서 도는 Three.js 기반 "새 비행 시뮬레이터"입니다. 갈매기 떼를 V자 편대로 조종해 바다 위를 날고, 낮·밤·폭풍·비·번개로 바뀌는 동적 날씨와 앰비언트 사운드를 입혔습니다. 점수도 미션도 없는 "게임이 아닌 힐링 경험" — 대신 그 안에는 Gerstner 파동 · 쿼터니언 slerp · PMREM 환경맵 · UnrealBloom · ACES 톤매핑 같은 실시간 그래픽과 게임 수학이 빽빽하게 들어 있어, WebGL/Three.js 학습 교본으로 손색이 없습니다. 이 문서는 사용법이 아니라 그 안의 그래픽·수학 설계를 해부합니다. (저장소: kanavtwtgg/birds.cafe · 언어 JavaScript 91.9% / HTML 4.2% / CSS 3.9% · 빌드툴 없음(순수 ESM) · 라이선스 없음(미지정) · 소스 ~2,800줄(JS ~2,523) · 2 커밋(일괄 업로드, 2026-06-21) · ★13 · 라이브 데모 birds.cafe · TrendShift Weekly #12)

1프로젝트 한줄 요약

"게임은 '점수로 이기는 것'을 안다. birds.cafe는 '브라우저에서 바다 위를 나는 기분'을 만든다 — 그 뒤엔 묵직한 그래픽 수학이 숨어 있다."

좀 더 구체적으로, birds.cafe는 약 2,800줄(JS는 2,523줄)의 순수 ES 모듈로 짜인 프런트엔드 전용 프로젝트입니다. 백엔드도, 데이터베이스도, 회원가입도, 점수 서버도 없습니다 — 정직하게 말하면 서버 측 코드가 단 한 줄도 없습니다. python -m http.server 같은 정적 서버 하나로 끝나고, Three.js와 텍스처·사운드 같은 에셋은 전부 CDN/외부에서 불러옵니다. 핵심은 js/main.js(1,141줄)라는 오케스트레이터가 씬·렌더러·후보정·날씨 전환·입력·오디오·애니메이션 루프를 총괄하고, 그 아래 flock.js·weather.js·ocean/·clouds/·islands/·birds/ 같은 도메인 모듈이 각자 한 가지 일을 맡는 모듈러 구조입니다.

이 문서가 파고드는 건 "어떻게 조작하나"가 아니라 그 안의 그래픽·수학입니다 — "출렁이는 바다는 어떤 공식으로 만드나(Gerstner 파동)", "갈매기가 회전해도 절대 뒤집히지 않는 이유(월드업 구속 뱅킹 + 쿼터니언 slerp)", "날씨가 매끄럽게 바뀌는 비결(데이터 주도 보간)". WebGL·셰이더·게임 수학을 처음 공부하는 사람에게 작지만 알찬 교본입니다.

2왜 주목받는가

"화려한 데모는 많다. birds.cafe가 눈에 띄는 건 '게임이 아닌 분위기'라는 컨셉 + 실제 배포 + 번들러 없이 보여준 완성도, 이 셋의 결합이다."

먼저, 이 작은 레포가 트렌딩에 오른 이유

솔직히 짚고 가겠습니다. birds.cafe는 ★13 · 커밋 2개 · 한 명의 개발자가 만든 작은 프로젝트입니다. 거대한 프레임워크도, 수천 명의 기여자도 없습니다. 그런데도 TrendShift Weekly #12에 오른 이유는 "무엇을 만들었나"가 아니라 "어떻게, 어떤 감성으로 만들었나"에 있습니다.

그래서 무엇을 배우러 오는가

birds.cafe의 진짜 가치는 "작은 코드 안에 고급 실시간 그래픽 기법이 압축돼 있다"는 점입니다. 보통 이런 기법들(해양 시뮬레이션·후처리 파이프라인·환경맵 베이킹)은 거대한 게임 엔진 소스 깊숙이 숨어 있어 초보자가 따라가기 어렵습니다. 여기서는 2,800줄, 그것도 빌드 없이 읽히는 코드 안에 그 핵심만 교과서처럼 들어 있습니다.

3기술 스택 전체 지도

"코드의 91.9%가 JavaScript지만, 진짜 무게중심은 'Three.js 애드온 조합'과 'GLSL 셰이더 한 줄'에 있다. 백엔드는 — 없다."

먼저 정직하게 못 박겠습니다. birds.cafe에는 백엔드·데이터베이스·테스트·CI가 전혀 없습니다. 서버 측 언어(Node·Python·Go 등)도 없고, API 엔드포인트도 없습니다. 이건 순수 클라이언트(브라우저) 전용 프로젝트입니다. 따라서 "전체 지도"는 사실상 프런트엔드 그래픽 스택 + 인프라(배포)로 나뉩니다.

① 렌더링 코어 — Three.js r160 + 애드온

이 프로젝트의 심장은 Three.js와, 그 위에 얹은 공식 애드온(addons/examples)들의 조합입니다. importmap이 이들을 전부 jsDelivr CDN에서 직접 끌어옵니다.

② 그래픽 기법 — '한 줄짜리 마법'들

③ 에셋 · 오디오 · 입력

④ 인프라 — '빌드 없음'이 곧 인프라다

4아키텍처 심화 분석 (한 프레임이 그려지기까지)

"핵심은 단 하나의 루프 — 매초 60번, '입력→물리→날씨 보간→렌더(+블룸)'가 돈다. main.js가 지휘자, 나머지는 단원이다."

전체 구조 한 장 — 오케스트레이터 + 도메인 모듈

한 프레임은 이렇게 그려집니다. ① index.html이 importmap으로 Three.js를 잡고 main.js를 모듈로 로드합니다. ② main.js가 씬·렌더러·후보정 파이프라인을 세우고, 도메인 모듈들(weather·ocean·flock·clouds·islands·birds)을 조립합니다. ③ 그 뒤 requestAnimationFrame 루프(animate())가 시작돼, 매 프레임 — 시간 간격(dt)을 재고 → flock.update()로 새들을 조향하고 → 바다·구름·날씨를 보간하고 → 확률적으로 번개를 트리거하고 → composer.render()로 블룸까지 입혀 화면에 출력합니다. 이 한 줄이 초당 60번 돕니다.

설계 패턴 ① — 데이터 주도 날씨 전환 (lerpWeather)

가장 우아한 발상입니다. 날씨를 if (밤) {...} else if (폭풍) {...} 식으로 분기하지 않습니다. 대신 5개의 프리셋(dawn / day / dusk / night / storm)을 각각 ~25개의 파라미터 묶음(하늘 색·혼탁도·태양 위치·블룸 강도·안개·물 색…)으로 정의해 두고, 두 프리셋 사이를 t(0~1) 값으로 선형 보간(lerp)해 섞습니다.

// weather.js — 두 날씨 프리셋을 t로 동시에 섞는다 (색·벡터·스칼라 모두)
export function lerpWeather(a, b, t){
  const lerpC = (ca, cb) => ca.clone().lerp(cb, t);   // 색(Color) 보간
  return {
    skyTop:        lerpC(a.skyTop, b.skyTop),          // 하늘 위쪽 색
    turbidity:     lerp(a.turbidity, b.turbidity),     // 대기 혼탁도
    bloomStrength: lerp(a.bloomStrength, b.bloomStrength), // 블룸 세기
    fogDensity:    lerp(a.fogDensity, b.fogDensity),
    sunPosition:   a.sunPosition.clone().lerp(b.sunPosition, t),
    /* …총 ~25개 파라미터를 한꺼번에 보간… */
  };
}

설계 패턴 ② — 물리 기반 편대 비행 (월드업 구속 뱅킹 + slerp)

새가 회전할 때 비행기처럼 기울어지는(뱅킹, banking) 느낌을 주되, 절대로 뒤집히지(배가 하늘을 보지) 않게 하는 것이 관건입니다. birds.cafe는 yaw(좌우)·pitch(상하)를 lerp로 부드럽게 따라가게 하고, 기울기는 "월드 업(중력 반대 방향)"을 기준으로 구속(clamp)합니다. 그리고 최종 회전은 쿼터니언 slerp로 부드럽게 보간합니다.

// flock.js — 뱅킹을 주되, 새가 뒤집히지 않게 '월드 업'으로 구속
const finalUp = levelUp.clone().applyAxisAngle(forward, this.bankAngle);
if (finalUp.y < 0.2) this.bankAngle *= 0.7;   // 위쪽이 너무 누우면 기울기를 줄임(뒤집힘 방지)

// 현재 회전 → 목표 회전으로 '구면 선형 보간(slerp)' — 8*dt 비율로 부드럽게
this.smoothFlockQ.slerp(flockQ, Math.min(1, 8 * dt));

여기에 안정성을 위한 디테일이 더 붙습니다 — V자 편대를 위한 V_POSITIONS 11개 슬롯(리더 뒤로 좌우 번갈아 배치), 자연스러운 흔들림을 위한 난류 오프셋(turbulence), 그리고 보간 중 값이 깨질 때를 대비한 NaN 가드까지. "단순해 보이는 비행"이 사실은 여러 안전장치의 합작입니다.

설계 패턴 ③ — Gerstner 파동을 직접 GLSL로 (분산 관계 c=√(g/k))

이 프로젝트에서 가장 "그래픽 프로그래밍다운" 부분입니다. 진짜 바다처럼 출렁이는 파도를 만들기 위해, birds.cafe는 Gerstner 파동(trochoidal wave) 공식을 JavaScript에서 GLSL 셰이더 문자열로 동적 생성해 Water의 정점 셰이더에 주입합니다. 정점을 위아래로만 움직이는 게 아니라 옆으로도(원 운동) 굴려 파도 꼭대기가 뾰족해지는, 사실적인 형태를 만듭니다.

// ocean/GerstnerWaves.js — 8개 파동을 더해 정점 변위(displacement)를 만든다
float k = 6.28318 / wLen;          // 파수(wavenumber) = 2π / 파장
float c = sqrt(9.8 / k);           // ★ 분산 관계: 위상 속도 c = √(g/k), g=중력가속도
float f = k * (dir.x*wx + dir.y*wz - c * waveTime) + phase;
float a = steep / k;               // 가파름(steepness)을 진폭으로 환산

disp.x += dir.x * (a * choppiness * cos(f));  // 수평 변위(파도가 옆으로 굴러 뾰족해짐)
disp.y += a * sin(f);                          // 수직 변위(높낮이)

설계 패턴 ④ — 인스턴싱으로 구름을 '드로 콜 한 번'에

구름 한 덩이를 그릴 때마다 GPU에 "그려라" 명령(드로 콜, draw call)을 보내면, 구름이 수백 개면 명령도 수백 번 → 느려집니다. clouds/InstancedClouds.js는 InstancedMesh를 써서 같은 구름 모양을 위치·크기만 바꿔 단 한 번의 드로 콜로 전부 그립니다. GPU에게 "이 모양을, 이 위치 목록대로, 한꺼번에 그려"라고 말하는 것 — 대량의 동일 객체를 그릴 때의 정석 최적화입니다.

설계 패턴 ⑤ — 모바일 적응형 품질 저하

모바일 GPU는 데스크탑보다 약합니다. birds.cafe는 시작 시 IS_MOBILE을 감지해, 모바일이면 픽셀 비율(해상도)·블룸 강도·그림자 해상도·강수 입자 수를 동적으로 낮춥니다. "같은 코드, 다른 품질"로 한 코드베이스가 데스크탑의 화려함과 모바일의 부드러움을 모두 잡습니다. 반응형 디자인(@media)이 레이아웃을 바꾸듯, 여기선 렌더 품질 자체를 기기에 맞춥니다.

5디렉토리 구조 해부

"폴더 이름이 곧 책임이다. js/ 아래 한 폴더 = 한 가지 일. main.js가 이들을 엮는다."

최상위 한눈에

파일 크기로 본 무게중심

무게중심이 main.js(조립·루프)와 flock.js(비행 물리)에 쏠려 있습니다. 즉 이 프로젝트가 가장 공들인 건 "전체를 어떻게 매 프레임 돌리나"와 "새를 어떻게 자연스럽게 날리나"입니다. 그래픽 기법(Gerstner·인스턴싱)은 의외로 짧은 코드에 압축돼 있어, 오히려 학습용으로 읽기 좋습니다.

6학습 포인트 (기술별 — 배울 것 + 실습 아이디어)

"birds.cafe 한 레포 안에 셰이더·게임 수학·후처리·최적화·번들러리스 ESM이 다 들어 있다. 작아서 오히려 다 읽힌다."

① Gerstner 파동 — 해양 물리를 코드로

배울 것: 파동의 중첩(여러 파를 더함)·분산 관계(c=√(g/k))·가파름(steepness)이 파형에 미치는 영향. 정점을 수직만이 아니라 수평으로도 굴려 사실적 파도를 만드는 원리. 실시간 해양 렌더링의 기본기입니다.

실습: GerstnerWaves.js에서 파동 개수(8)를 2개로 줄여 보고, choppiness(뾰족함)와 steep 값을 키워 보며 잔잔한 호수 ↔ 거친 폭풍 바다가 어떻게 갈리는지 눈으로 확인.

② 쿼터니언 · slerp — 게임 수학의 핵심

배울 것: 오일러 각의 짐벌 락 문제와 쿼터니언이 그걸 어떻게 피하는지. slerp로 회전을 부드럽게 보간하는 법. "월드 업으로 구속"해 캐릭터가 뒤집히지 않게 하는 실전 트릭. 3D 게임/시뮬레이션이라면 어디서나 쓰입니다.

실습: flock.js의 slerp 비율(8*dt)을 2*dt나 20*dt로 바꿔, 새의 선회가 둔해지거나 너무 휙휙 도는 차이를 체감. finalUp.y < 0.2 가드를 지우면 새가 어떻게 뒤집히는지도 관찰.

③ PMREM 환경맵 · 실시간 반사

배울 것: 왜 반사를 위해 환경을 "텍스처로 굽나"(PMREM). PMREMGenerator.fromScene(sky)로 동적 하늘을 환경맵으로 만들어 수면이 그 하늘을 반사하게 하는 법. 거칠기(roughness)별 프리필터링의 개념.

실습: 날씨를 바꿨을 때 수면 반사가 따라 바뀌는지 확인하고, 환경맵 재생성(re-bake) 주기를 늘리거나 줄여 보며 "반사 품질 vs 성능"의 트레이드오프를 느껴 보기.

④ 포스트프로세싱 — EffectComposer · UnrealBloom · ACES

배울 것: "기본 렌더 → 효과 패스 → 출력"으로 이어지는 후처리 파이프라인 구성법. UnrealBloom으로 빛을 번지게 하는 원리(밝은 부분 추출 → 흐림 → 합성). ACES 톤매핑이 화면을 "필름처럼" 만드는 이유.

실습: main.js에서 UnrealBloomPass의 strength·threshold·radius를 조절해 발광이 과해지거나 사라지는 걸 관찰. toneMapping을 NoToneMapping으로 바꿔 ACES가 있고 없고의 색감 차이 비교.

⑤ atmospheric scattering — Sky로 하늘 그리기

배울 것: 하늘 색이 그림이 아니라 물리(빛의 산란)로 계산된다는 사실. turbidity(혼탁도)·rayleigh·태양 위치 파라미터가 새벽·정오·황혼·폭풍 분위기를 어떻게 만드는지.

실습: weather.js의 프리셋에서 turbidity와 태양 고도(sunPosition)를 바꿔 보며, 같은 Sky 셰이더로 전혀 다른 하늘이 나오는 걸 확인.

⑥ 인스턴싱 · 절차적 지오메트리 · 모바일 최적화

배울 것: InstancedMesh로 드로 콜을 줄이는 법(구름). 코드로 지형·새를 만드는 절차적 생성(Islands.js·LowPolyBird.js). IS_MOBILE 감지로 품질을 동적 조절하는 적응형 렌더링.

실습: 구름 수를 10배로 늘려 보고, 인스턴싱일 때와 (일부러) 개별 메시로 바꿨을 때 프레임 차이를 측정. 모바일 분기에서 낮추는 항목(픽셀비/블룸/섀도)을 하나씩 꺼 보며 영향 비교.

⑦ 번들러리스 ESM · importmap

배울 것: 빌드 도구 없이 import로 모듈을 쪼개고, importmap으로 'three' 같은 별칭을 CDN URL에 매핑하는 법. "정적 서버 하나로 끝나는" 배포의 단순함과, CDN 의존이라는 트레이드오프.

실습: index.html의 importmap에서 Three.js 버전(r160)을 다른 버전으로 바꿔 보고, 호환성 문제가 어디서 터지는지(애드온 경로 변경 등) 추적. 의존성을 로컬 파일로 내려받아 importmap을 로컬 경로로 바꿔 보기.

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

"Node도 DB도 빌드도 필요 없다. WebGL 되는 브라우저와, 정적 서버 하나면 끝 — 데스크탑이든 폰이든."

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

"띄워서 날려 보기 → 날씨/편대 손대기 → 파동 만지기 → 입력 추가 → 비행 로직 통째로 교체, 난이도별로."

9관련 기술 심화 학습 로드맵 (6주 플랜)

"Three.js 기초에서 출발해 셰이더·게임 수학·후처리·최적화·배포까지, birds.cafe를 길잡이 삼아."

10핵심 키워드 사전

"이 문서와 저장소에서 반복되는 그래픽·게임 수학 용어를 한곳에 모았다."

11참고 링크

• GitHub 저장소 — github.com/kanavtwtgg/birds.cafe (주의: LICENSE 미지정 — 코드 재사용 전 저자 확인 필요)
• 라이브 데모 — birds.cafe (브라우저에서 바로 체험)
• TrendShift 페이지 — trendshift.io/repositories/60836
• Three.js 공식 문서 — threejs.org/docs
• Three.js 예제(Sky / Water) — threejs.org/examples
• Gerstner waves 이론 — GPU Gems Ch.1 (Effective Water Simulation)