RoomCraft #18. 첫 배포 — WebGL + GitHub Pages, 그리고 아직 못 고친 한글 버그

소스코드 → github.com/Jywan/RoomCraft
플레이 → jywan.github.io/RoomCraft

들어가며

성능 정리까지 끝내고 나니 로드맵에 남은 게 배포뿐이었다. 지금까지는 전부 에디터 안에서만 돌아가던 걸, 이번에 처음으로 브라우저에서 아무나 접속해서 플레이할 수 있게 내보냈다. 무료로 되는 방법부터 찾다가 GitHub Pages로 정했고, 가는 길에 예상 못 한 버그를 두 개 만났다.

---

무료 배포처 고르기

WebGL 기준으로 무료 옵션 몇 개를 놓고 비교했다.

• itch.io — 인디/하비 프로젝트 전시용으로 제일 무난한 선택지. zip만 올리면 끝
• GitHub Pages — 이미 코드가 올라가 있는 repo에 그대로 붙일 수 있어서, 소스코드랑 플레이 가능한 데모가 한곳에 묶인다는 장점

소스코드 링크를 이미 포트폴리오에 걸어둔 상태라, GitHub Pages 쪽이 자연스러웠다.

---

WebGL로 내보내기

먼저 Unity Hub에서 WebGL Build Support 모듈을 설치해야 했다 (Player Settings에 WebGL 탭 자체가 안 보이면 이게 원인). 설치하고 나서 빌드 전에 설정 하나를 바꿨다.

Player Settings → Publishing Settings → Compression Format을 Disabled로 바꿨다. Unity WebGL 빌드는 기본적으로 압축(gzip/brotli)된 파일을 만드는데, 이걸 풀려면 서버가 Content-Encoding 응답 헤더를 붙여줘야 한다. GitHub Pages는 순수 정적 호스팅이라 그런 커스텀 헤더 설정이 안 되고, 압축 켠 채로 올리면 브라우저가 파일을 못 풀어서 게임이 그냥 안 열린다. 압축을 꺼서 용량은 좀 커지지만, 어떤 정적 호스팅에서도 별도 설정 없이 바로 동작한다.

빌드 결과물(index.html, Build/, TemplateData/)을 repo 루트의 docs/ 폴더에 넣고, GitHub repo 설정에서 Settings → Pages → Source를 main 브랜치의 /docs 폴더로 지정했다.

jywan.github.io/RoomCraft — 실제로 접속되는 화면

---

삽질 기록

배포했는데 404

설정 끝내고 접속했더니 흰 화면에 콘솔 에러만 떴다.

Failed to load resource: the server responded with a status of 404 ()
build.loader.js:1

git ls-files docs/로 확인해보니 docs/Build/ 폴더 자체가 커밋된 적이 없었다. 원인은 .gitignore에 있던 규칙 하나.

[Bb]uild/
[Bb]uilds/

Unity 프로젝트 템플릿에 원래 있던 규칙인데, 앞에 /가 없어서 경로 어디에 있든 이름이 Build/build인 폴더를 전부 무시해버린다. Unity 자체 빌드 산출물을 걸러내려던 규칙이 docs/Build/까지 같이 잡아먹은 것. 예외 규칙 한 줄로 풀었다.

!docs/Build/

덤으로 docs/Build/build.wasm이 55.64MB라 GitHub 권장 최대치(50MB)를 넘는다는 경고도 떴다. 차단 기준(100MB)보다는 작아서 일단 정상 푸시는 됐는데, 나중에 빌드가 더 커지면 Git LFS를 써야 할 수도 있다.

한글이 낱자로 깨져서 들어감

404를 고치고 다시 들어가서 방 이름에 "테스트방"을 입력했는데, 결과는 이랬다.

"테스트"라고 쳤는데 조합 전 낱자가 그대로 들어간다

에디터에서는 멀쩡히 되는데 WebGL에서만 이런다. 원인을 찾아보니 이건 내 코드 버그가 아니라 Unity WebGL 자체의 한계였다. 한글 입력은 자음/모음을 IME가 조합해서 완성된 글자를 넘겨주는 방식인데(compositionstart / update / end 이벤트), Unity WebGL의 키보드 입력은 브라우저의 keydown 이벤트를 그대로 받아서 처리한다. 조합이 끝나길 기다리지 않고 매 keydown마다 바로 글자를 넣어버리니, 조합 중이던 낱자가 그대로 노출되는 것.

제대로 고치려면 브라우저의 compositionend 이벤트를 직접 받아서 완성된 글자만 Unity로 넘기는 JS 플러그인이 필요해 보인다. WebGL 빌드 파이프라인에 커스텀 JS를 끼워 넣는 작업이라 이번 배포 범위에서 바로 끝낼 순 없었고, 일단 알려진 제약으로 기록해두고 다음에 시간 내서 방법을 찾아볼 생각이다.

---

정리

작업	핵심 내용
배포처	GitHub Pages (docs/ 폴더 기반)
WebGL 빌드 설정	Compression Format → Disabled (정적 호스팅 헤더 제약 회피)
404 버그	.gitignore의 [Bb]uild/ 규칙이 docs/Build/까지 무시 → 예외 규칙 추가
한글 입력 버그	Unity WebGL이 IME 조합을 못 기다림 — 알려진 제약으로 남김
다음 단계	Phase 6-2 모바일(Android/iOS) 빌드 배포