97KB HTML로 만든 WebGPU 3D 수중 바다
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 라이선스라 회사 프로젝트에도 쓸 수 있음
댓글