본문으로 이동

97KB HTML로 만든 WebGPU 3D 수중 바다

geul조회 8추천 0댓글 0
  • Abyssal Garden(어비설 가든)은 개발자 Noniv가 11월 12일 공개한 3D 바닷속 데모임. 브라우저에서 바닷속을 헤엄쳐 다닐 수 있음

  • 이미지, 3D 모델, 소리 파일 없이 전부 코드로 만들었고, HTML 파일 하나(약 97KB)에 다 들어감

  • 게임 엔진 없이 WebGPU로 직접 구현함. 지형과 물체는 파일로 저장해 두지 않고, 페이지를 열 때 코드로 만들어 냄

  • 보도에 따르면 Claude Code와 Claude Fable 5.2로 만들었고, 처음 쓴 프롬프트도 저장소에 공개함

  • 크롬이나 엣지에서 바로 해 볼 수 있음 (https://noniv.github.io/abyssal-garden/)

Abyssal Garden이란, 반응은

마우스와 WASD 키로 바닷속을 헤엄치며 구경하는 데모임. 목표나 점수가 있는 게임은 아님.

  • 켈프 숲, 수면에서 쏟아지는 햇빛 줄기, 가라앉은 배, 쥐가오리, 물고기 떼, 보라색 동굴이 있음

  • GitHub 스타를 11월 14~15일 이틀 동안 약 1,000개 받음 (11월 16일 기준 1,076개)

  • Hacker News에는 "말문이 막힌다", "아이폰 사파리에서도 끊김 없이 돌아간다"는 댓글이 달림

  • "심해(abyssal)가 아니라 햇빛 드는 얕은 바다라고 따지면 트집이겠지"라는 농담도 나옴

  • 성능 수치는 개발자가 직접 잰 것이라 검증되지 않았다는 지적이 있음 (Wccftech)

97KB 안에 든 기술 스택

이미지 파일 대신 이미지를 그려 내는 코드를 담아서 용량이 작음.

  • 화면은 WebGPU와 WGSL(WebGPU용 셰이더 언어)로, 소리는 Web Audio API로 만듦

  • 외부 라이브러리 없이 빌드 도구 esbuild 하나만 씀

  • 소스 파일 6개를 줄여서(minify) HTML 하나에 합침

  • 완성 파일은 99,514바이트이고, 그중 약 3분의 1이 셰이더 코드임

  • 여러 셰이더가 공통 코드를 나눠 쓰고, 셰이더 하나를 설정값만 바꿔 여러 곳에 씀

  • 이런 방식은 예전부터 있었음. 2004년 데모신(코드로 영상과 음악을 만드는 해커 문화)에서 나온 슈팅 게임 .kkrieger도 96KB였음

바닷속을 코드로 구현한 원리

로딩할 때 지형, 물체, 그림자를 한꺼번에 만들어 두고, 그 뒤로는 그리기만 함.

  • 지형은 SDF로 만듦. 공간의 각 지점이 바위 표면에서 얼마나 떨어져 있는지 숫자로 적은 지도임

    • GPU가 바닷속을 약 2천만 칸으로 나눠 한꺼번에 계산함

    • 노이즈(불규칙한 무늬를 만드는 함수)를 겹쳐 바위 표면을 울퉁불퉁하게 만듦

    • 아치는 고리 모양을 붙이고, 터널은 캡슐 모양으로 파냄. 붙인 자리는 smooth min이라는 함수로 둥글게 이어 티가 안 나게 함

    • 다 계산한 지도는 CPU가 받아서 화면에 그릴 수 있는 삼각형 면으로 바꿈 (surface nets 방식)

  • 가라앉은 배는 선체 모양을 수식으로 정한 뒤, 뼈대와 판자를 붙이고 곳곳에 구멍을 냄

  • 바위는 공 모양을 울퉁불퉁하게 찌그러뜨려 만듦

  • 해면(통 모양 바다 생물)은 도자기를 물레로 빚듯 옆모습을 한 바퀴 돌려 만듦

  • 켈프가 흔들리고 물고기 꼬리와 쥐가오리 날개가 움직이는 건 모두 셰이더가 시간에 따라 계산함

  • 물속 같은 느낌은 대부분 안개 색에서 나옴. 물이 빨간빛을 먼저 흡수하는 성질을 따라, 가까운 곳은 청록색, 먼 곳은 짙은 파란색으로 보이게 함

  • 햇빛 줄기는 ray marching으로 그림. 픽셀마다 시선 방향으로 조금씩 나아가며 그 자리에 닿는 빛을 더하는 방식임

성능 최적화, 무거워 보여도 부드럽게 돌아가는 이유

무거운 계산은 로딩할 때 끝내 두고, 화면을 그릴 때는 보이는 것만 그림.

  • 개발자가 잰 결과, RTX 5070 Ti 그래픽카드에서는 2560×1440 해상도로 약 180fps가 나옴

  • 저가폰인 갤럭시 A16에서는 가장 낮은 품질로 약 20fps임

  • 바닷속을 바둑판처럼 칸으로 나누고, 화면에 안 보이는 칸은 그리지 않음

  • 멀리 있는 잎은 수를 줄이고, 먼 바위는 단순한 모양으로 바꿔 그림 (LOD)

  • 카메라 위치 같은 값은 미리 만들어 둔 배열에 담아 다시 씀. 브라우저가 메모리를 정리하느라 화면이 순간 멈추는 일을 줄이려는 것임

  • 느려지면 해상도부터 낮추고, 그래도 느리면 멀리까지 그리지 않음. 이 조정은 시작 메뉴가 떠 있는 동안 뒤에서 미리 끝냄

  • 로딩하다 탭이 꺼지면 다음에 열 때 한 단계 낮은 품질로 시작함

  • 바위에 부딪히는 처리도 물리 엔진 없이, 지형을 만들 때 쓴 숫자 지도를 그대로 활용함

AI에게 어떻게 시켰나, 공개된 프롬프트

프롬프트에는 어떻게 만들지보다 지켜야 할 조건과 합격 기준이 주로 적혀 있음.

  • Wccftech에 따르면 Claude가 실제로 작업한 시간은 2~3시간이고, 사용량 제한에 걸려 사흘쯤에 걸쳐 나눠 작업함

  • 저장소에는 어떤 모델을 썼는지 나와 있지 않음. Claude Fable 5.2는 보도에 나온 이름임

  • 우선순위는 화질, 끊김 없는 화면, 작은 용량 순으로 정함

  • 게임 엔진과 이미지, 모델 파일은 쓰지 못하게 막고, 한 프레임을 몇 ms 안에 그려야 하는지 숫자로 정함

  • 코드는 보지 않고 화면만 보는 "시각 비평가" AI를 따로 둠

  • 비평가가 깜빡임, 계단 현상 같은 문제를 찾으면 고치고, 사소한 문제만 남을 때까지 되풀이함

  • 첫 커밋부터 장면은 다 만들어져 있었고, 그 뒤에 메뉴, 품질 단계, 충돌, 터치 조작을 하나씩 붙임

따라 쓸 수 있는 프롬프트 예시

원본 프롬프트의 틀을 살려 다른 주제와 후속 작업에 맞게 고쳐 본 예시임. 주제와 컴퓨터 사양만 바꾸면 그대로 쓸 수 있음.

  • 무엇을 만들지, 어떻게 되면 합격인지만 쓰고 만드는 방법은 AI에게 맡김

  • 첫 장면을 만든 뒤에는 프롬프트 하나에 기능 하나씩만 시킴

  • 추가 요청마다 "지금 성능은 그대로 유지"를 붙임. 기능을 더하다 슬그머니 느려지는 일을 막을 수 있음

첫 프롬프트, 장면 전체를 한 번에

숫자로 정한 합격선과 화면만 보는 검토자, 이 두 가지가 품질을 끌어올림. 둘이 없으면 AI가 적당한 데서 "다 됐다"고 멈춤.

브라우저에서 실시간으로 돌아가는 "안개 낀 밤 숲"을 만들어 줘.
아름답게 보이고, 카메라를 자유롭게 움직이며 둘러볼 수 있으면 돼.

우선순위 (서로 부딪히면 이 순서)
1. 화질
2. 목표 사양에서 끊김 없는 화면
3. 작은 용량

제약
- 엔진(Three.js, Babylon.js) 금지. WebGPU로 직접 그림
- 이미지, 모델, 소리 파일 금지. 전부 코드로 만듦
- 결과물은 index.html 한 파일. 압축 후 크기 보고
- 매 프레임 JS 메모리 할당 금지. 버퍼는 미리 만들어 둠

목표 사양
- Windows 11, 최신 Chrome, RTX 4070, 2560x1440
- GPU 프레임 시간 평균 11ms 이하
- 정해진 경로로 60초 날아가는 동안
  16.7ms를 넘는 프레임 없음

장면
- 키 큰 침엽수 숲, 나무 사이를 떠다니는 반딧불
- 멀어질수록 짙어지는 푸른 안개, 달빛 줄기
- 이끼 낀 바위, 쓰러진 통나무, 작은 개울
- 세계 끝은 있지만 시작 지점에서는 안 보이게

조작
WASD 이동, 마우스 시점, Q/E 위아래, Shift 가속

검증
- 시각 비평가: 코드는 못 보고 렌더 결과만 보는
  별도 서브에이전트. 고정 시점 6곳 스크린샷과
  비행 녹화를 주고, "사소함"보다 큰 문제가
  없을 때까지 반복
- 성능: GPU timestamp query와 60초 비행의
  프레임 시간 기록. 평균, 상위 1%, 최댓값 보고

완료 조건: 두 검증 통과. index.html, 용량,
성능 보고, 비평가 최종 평가를 전달

측정 도구를 먼저 만들게 하기

이후 최적화는 모두 이 도구로 잰 숫자를 보고 함. 첫 장면을 만든 바로 다음에 시키면 좋음.

index.html과 별도로 개발용 dev.html을 만들어 줘.
- F 키: 정해진 경로로 세계 전체를 60초 동안 비행
- B 키: 같은 경로를 날며 성능 측정. 해상도는 고정하고
  매 프레임 CPU, GPU 시간을 기록해서 끝나면
  평균, 상위 1%, 최댓값을 화면에 띄움
- 이 기능은 index.html 용량에 들어가면 안 됨

시각 비평가에게 줄 지시

작업하는 AI가 검토용 AI를 따로 띄울 때 넘겨주는 지시문임. 검토용 AI가 코드를 보지 못하게 하는 게 중요함.

너는 실시간 그래픽 화질 검수자야.
코드는 볼 수 없고, 첨부한 스크린샷과 영상만 보고 판단해.
아래 문제를 찾아 심각도(치명, 큼, 보통, 사소함) 순으로 적어 줘.
- 계단 현상, 깜빡임, 물체가 갑자기 나타나거나 사라짐
- 색 띠, 너무 어둡거나 하얗게 날아간 곳
- 떠 있는 물체, 땅에 묻힌 물체, 티 나는 반복 무늬
- 장면 설명(첨부)과 분위기가 다른 곳
몇 번 사진의 어디인지, 어떻게 보여야 맞는지 적어 줘.
고치는 방법은 쓰지 마.
  • 마지막 줄이 있어야 비평가가 짐작으로 고칠 방법을 늘어놓지 않고, 보이는 문제만 정확히 짚음

기능은 하나씩 추가

시작 메뉴와 자동 해상도:

시작 메뉴, 로딩 막대, 자동 해상도를 넣어 줘.
- 로딩 진행률을 보여 주고, 끝나면 "시작" 버튼이 있는 메뉴를 띄움
- 메뉴 뒤에는 장면이 흐릿하게 이미 움직이고 있어야 함
- 느린 기기는 60fps를 목표로 해상도부터 낮추고,
  그래도 느리면 그리는 거리를 줄임
- 이 조정은 메뉴가 떠 있는 동안 미리 끝냄
- 결과는 localStorage에 저장해 다음에 열 때 씀
- 지금 벤치마크 성능보다 나빠지면 안 됨

저사양 기기와 휴대폰 대응:

낮음, 중간, 높음 품질 단계를 추가해 줘.
- 세 단계 모두 같은 장면이고, 풀과 바위 같은 물체 수만 다름
- 처음 열 때는 기기 메모리와 터치 화면 여부를 보고 자동으로 고름
- 로딩하다 탭이 꺼지거나 그래픽 드라이버가 멈추면
  다음에는 한 단계 낮춰 시작
- 확인 기준: 메모리 4GB 안드로이드폰의 Chrome에서
  낮음 단계로 끝까지 로딩되고 20fps 이상 나옴

충돌:

카메라가 바위와 지형을 뚫고 지나가지 못하게 해 줘.
- 부딪히면 멈추지 말고 표면을 따라 미끄러지게
- 모든 터널과 아치는 지금처럼 지나갈 수 있어야 함
- 풀과 작은 장식물은 그냥 통과해도 됨
- 물리 엔진은 쓰지 않음. 지금 프레임 시간 기준은 그대로 지킴
  • 지나갈 수 있어야 하는 곳도 꼭 적어야 함. 안 적으면 AI가 충돌 범위를 넉넉하게 잡아서 터널을 막아 버리기 쉬움

버그는 원인 대신 보이는 증상을 쓰기

원 저장소에서 공중에 뜬 바위 부스러기를 지운 커밋 같은 경우임. 무엇이 잘못 보이는지, 무엇은 건드리면 안 되는지, 고친 걸 어떻게 확인할지만 적으면 됨.

첨부한 3번 시점 사진을 보면 절벽 위 허공에
작은 바위 조각들이 떠 있어.
바닥이나 큰 바위와 이어지지 않은 조각은 없어야 해.
일부러 띄워 둔 큰 바위는 그대로 둬.
고친 뒤 같은 6개 시점으로 다시 찍어서 비교해 줘.

용량 줄이기와 코드 공부

index.html 용량을 더 줄여 줘. 화질과 성능은 지금과 같아야 해.
- 먼저 지금 용량을 JS, 셰이더, HTML/CSS별로 나눠 알려 줘
- 겹치는 셰이더 코드와 안 쓰는 코드를 찾아 줄임
- 바꾼 뒤 비평가 검사와 벤치마크를 다시 돌려 확인
- 줄어든 바이트 수를 항목별로 보고

결과물만 받고 끝내면 배우는 게 없음. 다 만든 뒤에는 코드 설명도 시켜 볼 만함.

지형을 만드는 부분을 WebGPU 입문자에게 설명해 줘.
- 어느 파일 몇 번째 줄에서 무슨 일이 일어나는지 순서대로
- 쓰인 개념(SDF, noise, surface nets)마다 공부 자료 하나씩
- 직접 바꿔 볼 만한 숫자 3개와, 바꾸면 화면이 어떻게 달라지는지

시작하기 전에 챙길 것

  • AI가 결과 화면을 직접 볼 수 있어야 함. Claude Code가 그래픽 가속을 켠 크롬을 열어 스크린샷과 영상을 찍을 수 있게 미리 연결해 둠

  • 목표 사양은 내 컴퓨터 기준으로 적음. 그래야 AI가 직접 재 보면서 맞출 수 있음

비슷한 걸 만들려면, 알아야 할 것과 개발 순서

이 저장소는 파일마다 맡은 일이 나뉘어 있어서 공부 자료로 쓰기 좋음.

  • 알아야 할 것

    • WebGPU 기본(파이프라인, 렌더 패스, 컴퓨트 셰이더): WebGPU Fundamentals(webgpufundamentals.org)부터 보면 됨

    • 코드로 모양 만들기(SDF, smooth min, 노이즈): 이 분야에서 가장 많이 보는 자료가 Inigo Quilez 블로그(iquilezles.org)임

    • 물체를 많이 그리기: 같은 모델을 한 번에 수만 개 그리는 인스턴싱, 안 보이는 것 빼기(컬링), 거리별 단순화(LOD)

    • 물속 빛 표현: 안개, ray marching, 블룸(밝은 곳이 번지는 효과), 톤 매핑(밝기를 화면에 맞게 조절)

  • 개발 순서

    • 화면에 삼각형 하나를 띄우고 카메라를 움직여 보는 데서 시작함

    • 지형을 만들고 안개 색부터 맞춤. 이것만으로도 물속처럼 보임

    • 바위, 해초, 물고기를 배치하고 햇빛 줄기와 바닥에 일렁이는 빛무늬를 더함

    • 성능 재는 도구는 일찍 만듦. 이 저장소에도 정해진 경로를 날며 프레임 시간을 재는 개발용 기능이 있음

    • 마지막에 품질 단계를 붙이고 한 파일로 묶음

  • 직접 고쳐 보려면 source 폴더에서 npm install, npm run build를 실행함

  • 물 색을 바꾸고 싶으면 shaders.js의 WCOL 값을 고치면 됨

자주 묻는 질문

  • 파이어폭스나 사파리에서도 되나?

    • 개발자는 데스크톱 크롬, 엣지를 권함. WebGPU를 지원하지 않는 브라우저에서는 안내 문구만 뜸

  • 휴대폰에서 되나?

    • 터치 조작을 실험적으로 지원하고, 휴대폰에서는 낮음이나 중간 품질로 시작함

  • 코드를 가져다 써도 되나?

    • MIT 라이선스라 회사 프로젝트에도 쓸 수 있음

추천저장

댓글

댓글을 남겨 보세요
로그인한 뒤에 댓글을 올릴 수 있습니다로그인
아직 댓글이 없습니다. 처음으로 남겨 보세요.
글쓰기