Claude Opus 5.5로 생성한 3가지 3D 웹 게임: 로컬 빌드 및 플레이 가이드

프로젝트 소개

claude-opus-5-5-demo는 Claude Opus 5.5의 코드 생성 능력을 실험한 프로젝트입니다. 저장소에는 바로 플레이할 수 있는 3개의 3D 웹 게임이 포함되어 있으며, 각 프로젝트는 하나의 프롬프트만 사용해 단일 Claude Code 세션에서 자료 조사, 프로젝트 구성, 코딩, 빌드, 테스트와 배포를 완료했습니다.

저장소 설명에 따르면 세 게임의 소스 코드는 모두 모델이 생성했으며, 사람이 코드를 수정하지 않았습니다. 프로젝트는 Three.js로 3D 장면을 구성한 다음 esbuild를 사용해 프로그램을 하나의 HTML 파일에 번들하고 인라인 처리합니다. 모델, 텍스처, 애니메이션과 효과음은 모두 코드로 절차적으로 생성되며, 외부 이미지나 오디오 또는 서드파티 리소스에 의존하지 않습니다.

이는 전통적인 게임 개발 템플릿이 아니라 실행, 빌드와 검증이 가능한 one-shot 코드 생성 실험 결과물입니다.

세 게임과 주요 특징

자전거를 타는 펠리컨

해안 도로를 여유롭게 달리는 게임입니다. 플레이어는 헬멧과 선글라스를 쓰고 빨간 스카프를 두른 펠리컨을 조종해 자전거를 타고 물고기를 잡습니다. 천 물리 기반 스카프, 파도와 해안의 포말, 낮과 밤의 순환, 절차적으로 생성되는 효과음과 음악, 프레임 속도에 따라 화질을 자동 조정하는 기능이 포함되어 있습니다.

• W, S: 가속 및 감속.
• A, D: 차선 변경 및 물고기 접근.
• 스페이스바: 점프.
• T: 날개를 펼치고 앞바퀴 들기.
• 자동 운전: 오랫동안 조작하지 않으면 펠리컨이 자동으로 물고기를 따라갑니다.

게임에는 14개의 업적, 5가지 카메라 모드, 터치 버튼, 페달링 속도에 따라 변하는 브라우저 실시간 합성 음악도 제공됩니다.

자전거를 타는 펠리컨 온라인 플레이

크로스파이어·수송선

이 프로젝트는 《크로스파이어》의 고전적인 수송선 맵을 재현하려고 시도합니다. 생성 과정에서 먼저 배치도와 공략을 검색한 뒤, 긴 갑판, 양쪽 선실의 시작 지점, 중앙에 V자 형태로 배치된 컨테이너, 양측의 일방통행 통로 등의 특징을 바탕으로 장면을 구성했습니다.

총기 탄도, 반동, 봇 AI 대전, 피격 피드백, 처치 알림, 절차적으로 생성되는 총성과 기타 효과음을 지원하며 터치 조작도 가능합니다.

크로스파이어·수송선 온라인 플레이

QQ 스피드

레이싱 프로젝트는 Shift 드리프트, Ctrl 니트로, 소형 부스트, 더블 부스트와 리셋 등의 조작을 재현하고, 공식 맵 스타일로 설계한 4개의 트랙을 제공합니다.

• 십일성: 11개의 커브와 헤어핀 커브가 있는 도시 야경 트랙.
• 사랑에 빠진 에게해: 오르막과 연속 커브가 주요 특징입니다.
• 파라오의 피라미드: 직선 구간 끝에 점프대를 배치했습니다.
• 설원 대모험: 8자 형태의 입체 교차 구조를 사용합니다.

정식 개발 전에는 스크립트로 트랙 형태의 평면도를 먼저 생성해 커브 배치와 교차점을 점검했습니다.

QQ 스피드 온라인 플레이

시작 전 준비

로컬 빌드에는 npm과 Node.js 스크립트를 실행할 수 있는 환경이 필요합니다. 저장소에는 node_modules/와 dist/가 포함되어 있지 않으므로 소스 코드를 클론하거나 다운로드한 후, 플레이할 게임마다 의존성을 설치하고 빌드를 실행해야 합니다.

세 하위 프로젝트는 서로 독립되어 있어 하나만 빌드하거나 차례대로 모두 빌드할 수 있습니다. 주요 의존성은 Three.js와 esbuild입니다.

저장소 구조

pelican-bike/
  src/
  index.template.html
  build.mjs
  package.json

cf-transport-ship/
  src/
  build.mjs
  package.json

qq-speed/
  src/
  build.mjs
  wrangler.jsonc
  package.json

pelican-bike/src/에는 펠리컨, 자전거, 바다, 물고기, 하늘, 효과와 오디오 등을 담당하는 11개의 모듈이 있습니다. cf-transport-ship/src/에는 맵, 총기, 무기, 봇, 플레이어, 물리와 1인칭 무기 모델을 담당하는 18개의 모듈이 있습니다. qq-speed/src/에는 차량, 트랙, 레이아웃, AI, 맵과 아이템을 담당하는 15개의 모듈이 있습니다.

설치 및 빌드

방법 1: 자전거를 타는 펠리컨 빌드

cd pelican-bike
npm install
node build.mjs

방법 2: 크로스파이어·수송선 빌드

cd cf-transport-ship
npm install
node build.mjs

방법 3: QQ 스피드 빌드

cd qq-speed
npm install
node build.mjs

각 프로젝트의 빌드가 완료되면 결과물이 해당 디렉터리의 dist/index.html에 저장됩니다. 저장소에서 안내하는 방식대로 이 파일을 브라우저에서 직접 열면 플레이할 수 있습니다.

세 빌드 결과물의 크기는 약 700 KB에서 840 KB입니다. JavaScript가 HTML에 번들되어 있으므로 실행 시 게임 모델, 텍스처나 효과음 리소스를 추가로 불러올 필요가 없습니다.

기본 사용 절차

1. 세 하위 디렉터리 중 하나의 게임을 선택합니다.
2. 해당 디렉터리로 이동해 npm install을 실행합니다.
3. node build.mjs를 실행합니다.
4. dist/index.html이 생성되었는지 확인합니다.
5. 브라우저에서 이 파일을 엽니다.
6. 게임 유형에 따라 키보드 또는 터치 컨트롤로 플레이를 시작합니다.

소스 코드를 확인하거나 다시 빌드하지 않고 빠르게 체험하려면, Cloudflare Pages 또는 CDN에 배포된 프로젝트의 온라인 주소를 직접 열면 됩니다.

단일 파일 빌드 방식 이해하기

여기서 말하는 “단일 파일 HTML”은 최종 페이지가 번들된 JavaScript를 HTML에 인라인 처리한다는 의미입니다. src/는 개발과 유지보수를 위해 여전히 기능별 여러 모듈로 나뉘어 있으며, build.mjs를 실행하면 esbuild가 이 모듈을 브라우저에서 실행 가능한 결과물로 통합합니다.

펠리컨 프로젝트는 index.template.html을 페이지 템플릿으로 사용하며, 빌드 과정에서 번들된 JavaScript와 og:image를 주입합니다. 저장소에는 소스 파일만 커밋되어 있으므로 소스를 수정한 후에는 빌드 스크립트를 다시 실행해야 새로운 dist/index.html을 얻을 수 있습니다.

심화 학습 및 디버깅 제안

모듈별로 기능 찾기

코드를 읽을 때 완성된 빌드 결과물부터 살펴볼 필요는 없습니다. 디렉터리의 모듈 이름을 기준으로 기능을 먼저 찾을 수 있습니다. 예를 들어 펠리컨 프로젝트에서는 바다, 하늘, 오디오 또는 효과 모듈을 확인하고, FPS 프로젝트에서는 총기, 봇, 플레이어와 물리 모듈을 확인하며, 레이싱 프로젝트에서는 차량, 트랙, AI와 맵 레이아웃을 확인하면 됩니다.

수정 후에는 항상 다시 빌드하기

개발할 때는 dist/index.html을 주요 소스로 사용하지 말고 src/의 소스 파일을 수정해야 합니다. 수정이 끝나면 다음 명령을 다시 실행합니다.

node build.mjs

dist/는 저장소에 포함되지 않으므로 저장소를 다시 클론하거나 작업 디렉터리를 정리한 후에도 다시 빌드해야 합니다.

장시간 안정성 점검

저장소 기록에 따르면 펠리컨 게임은 완전한 낮과 밤의 순환을 포함하기 위해 320초간 가속 침투 테스트를 받았으며, 지오메트리 수, 텍스처 수와 JavaScript 힙 메모리가 안정적인지 관찰했습니다. 또한 36킬로미터 주행 거리의 모듈러 경계도 별도로 테스트했습니다.

무한 도로, 낮과 밤 시스템, 파티클, 바다 표면 또는 텍스처 로직을 수정했다면 비슷한 방식으로 장시간 게임을 실행해 리소스 수가 계속 증가하는지 관찰하고, 주행 거리, 타이머와 순환 애니메이션의 경계 조건을 테스트할 수 있습니다.

유효하지 않은 값이 후처리에 미치는 영향 확인

프로젝트가 출시된 후 간헐적으로 검은 화면이 나타나는 문제가 발생했습니다. 기록에 따르면 NaN을 주입해 문제를 재현했고, Bloom 후처리가 유효하지 않은 픽셀을 검은 블록으로 확산시키는 것이 원인으로 확인되었습니다. 수정 방법에는 블룸 처리 전에 정리 pass를 추가하고 바다 표면의 프레넬 효과 등 유효하지 않은 값의 원인을 처리하는 작업이 포함되었습니다.

이는 셰이더, 바다 표면, 조명 또는 후처리 코드를 수정할 때 문법 오류뿐 아니라 계산 결과에서 NaN이나 기타 유효하지 않은 값이 발생할 가능성도 확인해야 한다는 점을 보여줍니다.

조작 및 전체 대전 검증

원래 프로젝트는 헤드리스 브라우저를 사용해 페이지 로딩, 실행 오류와 키 입력 시뮬레이션을 확인하고 전체 대전을 실행했습니다. 게임 로직을 확장한 후에는 시작 과정, 키 입력 반응, 승패 조건, 리셋 동작과 장시간 실행 상태를 중점적으로 검증해야 하며, 홈페이지가 표시되는지만 확인해서는 안 됩니다.

배포 시 단일 파일의 장점 유지

빌드 결과물은 독립적인 dist/index.html이므로 정적 페이지 호스팅 서비스에 배포하기 좋습니다. 저장소의 세 게임은 이미 Cloudflare Pages에 배포되어 있으며, 그중 qq-speed/에는 wrangler.jsonc 배포 설정도 포함되어 있습니다. 실제 배포 전에는 먼저 로컬에서 빌드 결과물이 정상적으로 열리는지 확인한 다음 프로젝트 생성, 도메인 연결, 캐시 갱신과 인증서 상태를 처리해야 합니다.

프로젝트 범위 및 설명

• 세 게임은 Claude Opus 5.5가 Claude Code에서 생성한 성능 테스트 작품입니다.
• 저장소 설명의 생성 환경은 1M 컨텍스트와 xhigh 추론 강도를 사용했습니다.
• 각 게임에는 하나의 요구 프롬프트만 입력했으며 단일 세션에서 완성했습니다.
• 《크로스파이어》와 《QQ 스피드》 관련 프로젝트는 오마주 성격의 성능 테스트이며 원 제작사와 무관합니다.
• 저장소에 표시된 생성 시점은 2026년 9월입니다.

정리

claude-opus-5-5-demo는 하나의 프롬프트로 완성된 3D 웹 게임을 생성한 결과를 보여주며, 검토할 수 있는 모듈식 소스 코드와 통합 빌드 과정도 제공합니다. 하위 프로젝트 중 하나를 선택해 의존성을 설치하고 node build.mjs를 실행하면 바로 열 수 있는 단일 파일 HTML을 얻을 수 있습니다. 더 깊이 학습할 때는 절차적 리소스 생성, 게임 모듈 분리, 장시간 안정성 테스트와 WebGL 후처리의 비정상 값 방어를 중점적으로 살펴볼 수 있습니다.