막혔을 때

증상을 고르고 오류 원문과 하려던 일을 함께 알려 주세요. 본문과 겹치는 해결 요청은 프롬프트 모음으로 연결했습니다.

1. 증상부터 찾기

2. 오류를 함께 전달하기

Chrome·Edge에서 Ctrl + Shift + J, Mac에서는 Cmd + Option + J로 Console을 엽니다. 문제 동작을 다시 해 보고 첫 오류를 복사하세요. 명령 실행 오류는 Code 탭의 실행 기록이나 터미널에서 복사합니다.

지금 [채팅 미리보기 / Code 탭 Local / 브라우저]에서 작업 중이야.
열어 본 주소: [file://... / http://localhost:... / 실제 배포 주소]
하던 일: [예: 청귤빛 버튼을 누름]
기대한 결과: [예: 한라봉 모델 색상이 바뀜]
실제 결과: [예: 글자는 보이지만 3D 영역이 비어 있음]
첫 오류: [오류 원문]
이 오류부터 원인을 찾고 수정한 뒤 같은 동작으로 확인해줘.

• Chrome 공식 개발자 도구 열기 안내

3. 증상별로 고치기

3.1 화면이 하얗습니다

원인: 코드·외부 모듈을 못 읽었거나 캔버스 크기·카메라·초기화에 문제가 있을 수 있습니다.

채팅 미리보기가 비었다면 HTML을 내려받아 Chrome이나 Edge로 엽니다. 모델 파일이 있는 상품·게임은 Code 탭의 Local 프로젝트에서 실행합니다.

OrbitControls를 넣은 뒤 재현한 오류입니다.

Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".

이 오류라면 Import Map에 three·three/addons/를 같은 CDN·0.186.1로 연결했는지 봅니다. 다른 오류는 원문을 그대로 보냅니다.

• 복사할 요청: 빈 3D 영역의 오류 전달

성공 기준: 글자와 도형이 함께 보이고 창을 좁혀도 3D 영역이 남습니다.

화면은 정상인데 아래 경고가 있다면 예전 그림자 옵션 때문입니다. PCFShadowMap으로 바꿔 달라고 요청하세요.

THREE.WebGLShadowMap: PCFSoftShadowMap has been removed. Using PCFShadowMap instead.

3.2 도형이 까맣습니다

원인: 조명·반사 환경 부족이나 재질·텍스처 로드 실패를 확인합니다. 빛을 받지 않는 재질도 있으니 종류부터 봅니다.

아래는 2장 3절에서 직접 조명과 환경 반사광을 끈 결과입니다.

도형의 윤곽은 있는데 표면이 까맣게 보여.
모델·텍스처 로드 오류를 먼저 확인하고, 사용하는 재질이 조명의 영향을 받는지 봐줘.
밝은 면과 어두운 면이 보이도록 조명·환경 반사·노출을 조정해줘.

성공 기준: 원래 색과 밝고 어두운 면이 구분됩니다.

3.3 모델이 안 보입니다

원인: 파일을 못 읽었거나 크기·중심·높이가 카메라 범위와 맞지 않을 수 있습니다.

글자와 바닥은 보이는데 모델이 안 보여.
GLB 요청 주소와 불러오기 성공 여부부터 확인해줘.
성공했다면 모델의 전체 크기·중심을 계산하고,
카메라가 전체를 보도록 크기·위치·바닥 높이를 맞춰줘.

성공 기준: 모델 전체가 보이고 드래그해도 잘리지 않습니다. 상품 완성본의 크기 맞추기와 비교해 보세요.

3.4 file 주소에서 안 열립니다

원인: 더블클릭한 file:// 페이지가 별도 모듈·GLB를 읽을 때 파일 접근 제한에 걸릴 수 있습니다.

상품 소스를 더블클릭했을 때 GLB보다 /src/main.js가 먼저 막혔습니다.

Access to script at 'file:///C:/src/main.js' from origin 'null' has been blocked by CORS policy
GET file:///C:/src/main.js net::ERR_FAILED

로컬 GLB를 읽은 다른 시험에서는 TypeError: Failed to fetch가 나왔습니다. 표시된 경로와 오류 원문을 함께 전달하세요.

• 복사할 요청: 더블클릭 대신 실행 주소 확인

완성본은 package.json이 있는 폴더에서 npm ci 후 npm run dev로 엽니다.

성공 기준: 안내받은 HTTP 주소에서 모델과 스타일이 보입니다.

npm error code ENOENT, Could not read package.json이면 실행 위치를 확인합니다.

• 복사할 요청: npm 실행 위치 확인

3.5 애니메이션이 안 나옵니다

원인: GLB에 동작이 없거나 클립 이름·재생·시간 갱신이 연결되지 않았을 수 있습니다.

제공 character.glb에는 Idle·Walk가 있습니다. 움직이는 방식은 리깅과 애니메이션에서 봅니다.

• 복사할 요청: 걷기 클립과 재생 확인

성공 기준: 멈추면 대기, 이동하면 걷기 동작입니다. 클립이 0개라면 제공 재료로 비교하거나 동작을 넣어 다시 내보냅니다.

FBX 변환에는 Blender·FBX2glTF 같은 도구가 필요합니다. 변환 요청과 점검 순서를 사용하세요.

3.6 소리가 안 납니다

원인: 경로·음소거·기기 음량이나 브라우저의 재생 거절을 확인합니다.

시작 버튼을 누르고 게임 설정과 기기 음량을 봅니다. NotAllowedError가 있다면 사용자 동작 안에서 재생을 요청했는지 확인합니다.

• 복사할 요청: 시작 후 소리 확인

성공 기준: 시작 뒤 음악이 나오고 음소거로 효과음까지 꺼집니다. 다시하기에서도 음악은 하나만 재생됩니다.

3.7 다시하기가 이상합니다

원인: 초기화가 빠졌거나 타이머·루프·음악·입력이 중복됐을 수 있습니다.

다시하기로 세 판 연속 확인합니다.

• 복사할 요청: 재시작 타이머 확인

성공 기준: 세 판 모두 표의 상태로 돌아옵니다. 4단계·소리를 넣은 5단계와 비교합니다.

3.8 배포 후 화면이 하얗습니다

원인: 배포가 끝나지 않았거나 JS·CSS 주소와 공개 경로가 다를 수 있습니다.

먼저 배포 상태와 실패 로그를 봅니다. Pages의 /my-game/ 같은 하위 경로는 Vite의 base도 맞춥니다. 위니버시티 앱 도메인의 루트는 보통 /입니다.

로컬에서는 되는데 배포 주소 [전체 주소]에서는 화면이 비어 있어.
배포 결과와 첫 Console 오류, 실패한 JS·CSS 요청 주소를 확인해줘.
Vite의 base가 실제 주소와 맞는지 보고, 같은 경로로 빌드와 preview를 실행해줘.
어떤 파일을 고쳤고 재배포할 묶음이 무엇인지 알려줘.
[오류 원문 또는 배포 실패 로그]

성공 기준: 재배포가 완료된 주소에서 화면이 보입니다. Actions를 썼다면 해당 작업의 성공도 봅니다.

3.9 배포 후 모델만 안 보입니다

원인: 파일 누락·대소문자·경로 또는 외부 텍스처·디코더를 확인합니다.

상품의 하위 경로 시험에서 GLB 주소를 /models/product.glb로 고정하자 난 오류입니다.

Failed to load resource: the server responded with a status of 404 (Not Found)

상품·게임 모두 모델은 public/models/, 소리는 public/sounds/에 둡니다. URL에는 public을 빼고 import.meta.env.BASE_URL을 반영합니다.

• 복사할 요청: 공개 후 모델 경로 수정

성공 기준: 빌드의 dist/models/·dist/sounds/와 공개 주소에서 파일이 읽힙니다. 응답이 성공했는데도 안 보이면 외부 참조·디코더 오류를 이어서 봅니다.

3.10 휴대폰에서 느립니다

원인: 큰 파일이나 픽셀 수·그림자·모델 복잡도가 부담일 수 있습니다.

첫 로딩이 긴지, 연 뒤 이동이 끊기는지를 구분하세요. 제공 모델·소리 5개는 합계 894,154바이트이고 최종판의 터치 픽셀 비율 상한은 1.5입니다.

파일 용량은 크기·압축 검토 요청으로 확인합니다. 이동이 끊긴다면 이어서 요청하세요.

휴대폰에서 이동이 끊겨. 픽셀 비율 상한과 그림자 품질을 낮춰 비교해줘.
한 가지씩 바꾸고 원래 값도 남겨줘.

성공 기준: 실제 휴대폰에서 로딩·이동을 다시 확인합니다. 손을 떼면 멈추고 버튼이 잘리지 않아야 합니다. 압축한 모델은 원본과 모습을 비교합니다.

3.11 사용량 한도에 걸렸습니다

원인: 현재 플랜·도구의 사용량을 모두 썼을 수 있습니다. 유료 구독에도 한도가 있습니다.

지금 파일을 그대로 두고 한도 화면이 알려 주는 시각까지 기다립니다. 다시 쓸 수 있을 때 첫 요청으로 이어받기 메모를 남기세요. 한도 경고가 보일 때 미리 보내도 좋습니다.

다음 작업 전에 이어받기 메모를 프로젝트에 남겨줘.
지금 되는 것, 남은 문제, 실행 방법, 다음에 할 일 하나를 적어줘.
다음 대화에서 어떤 파일을 열면 되는지도 알려줘.

새 대화를 열어도 한도는 채워지지 않습니다. 기다리는 동안 같은 단계의 완성본과 비교하세요. 간단한 페이지는 위니버시티 바이브 코딩의 무료 월 사용량·파일 크기 한도 안에서도 시도할 수 있습니다.

3.12 대화가 산으로 갔습니다

원인: 기준 파일·원하는 수정이 흐려졌을 수 있습니다.

잘 됐던 파일을 보관하고 새 대화의 기준으로 삼습니다. HTML은 첨부하고 폴더 프로젝트는 Code 탭 Local에서 엽니다.

이 파일들이 내가 이어갈 기준이야. [첨부한 HTML / 열린 프로젝트의 GAME.md]를 읽어줘.
지금 마음에 드는 점은 [예: 밝은 귤밭과 캐릭터 크기]이고,
이번에 고칠 것은 [예: 다시하기 뒤 남는 입력] 하나야.
고친 뒤 같은 동작으로 확인하고 결과를 알려줘.

실제 Git 커밋을 남겼다면 그 기록으로 돌아갈 수 있습니다.

현재 변경은 먼저 따로 보관하고, Git에서 잘 됐던 커밋을 찾아줘.
그 기록과 지금의 차이를 보여준 뒤, 문제가 생긴 파일을 그 상태로 복원해줘.
복원 뒤 실행해서 무엇이 돌아왔는지도 확인해줘.

성공 기준: 기준 화면이 열리고 고치기로 한 동작이 해결됩니다. 기록이 없다면 보관한 파일이나 단계별 ZIP부터 비교합니다.

4. 완성본과 비교하기

완성본은 내 작업과 다른 새 폴더에 풀어 같은 동작을 해 보세요.

• 프로필 카드
• 3D 자기소개
• 제주상점 한라봉
• 라이캣의 귤밭 산책 최종판
• 단계별 ZIP과 여는 법 전체 목록