Godot 게임을 웹 브라우저용으로 내보내기: 내보내기 템플릿, 파일 크기, 한글 글꼴, 올리기 전 확인할 것
Godot 4.7.2로 만든 작은 비행 게임을 웹(HTML5)으로 내보낸 실제 기록으로, 내보내기 템플릿 준비, 웹에서만 쓰는 렌더러, 스레드 설정, 40 MB 가까운 파일 크기와 압축, 웹에서 한글이 네모로 깨지지 않게 글꼴을 넣는 법, 내 PC에서 브라우저로 시험하는 법을 정리합니다.
한국어English
기준: Godot 4.7.2 stable(Windows), Godot 4.7 공식 문서(웹 내보내기, 글꼴). 2026년 11월 4일에 확인했습니다. 그림 1·3은 내보낸 웹 판을 실제로 실행한 화면이고, 그림 2는 내보낸 파일의 크기를 옮긴 도표입니다. 그림 1·3은 화면 없이 띄운 Chromium(소프트웨어 렌더)으로 찍어서, 그래픽카드를 쓰는 보통 브라우저와 그림자·색이 조금 다를 수 있습니다.
게임을 만들면 친구에게 보여 주고 싶어집니다. 실행 파일(.exe)을 보내면 받는 사람이 내려받아 설치해야 하고, 보안 경고도 뜹니다. 웹으로 내보내면 주소 하나만 보내면 됩니다. 받는 사람은 브라우저에서 바로 게임을 엽니다.
이 글은 Godot 4.7.2로 만든 작은 비행 게임 "협곡 돌파"를 웹으로 내보낸 기록을 바탕으로 씁니다. 처음 웹으로 내보내면 생각과 다른 곳이 몇 군데 있습니다. 화면을 그리는 방식이 바뀌고, 파일이 40 MB 가까이 되고, 한글이 네모로 깨질 수 있습니다. 하나씩 짚어 봅니다.
그림 1. 웹 판을 브라우저(Chromium)에서 연 처음 화면. 한글 제목과 안내가 넣은 글꼴로 보입니다 (브라우저 화면 캡처)
이 글을 마치면 아래를 할 수 있습니다.
- 웹 내보내기에 필요한 내보내기 템플릿을 준비합니다.
- 웹 판이 쓰는 렌더러와 스레드 설정을 확인합니다.
- 내보낸 파일 다섯 종류가 각각 무엇인지 구분합니다.
- 웹에서 한글이 보이도록 글꼴을 게임 안에 넣습니다.
- 내 PC에서 작은 서버를 띄워 브라우저로 시험합니다.
1. 웹으로 내보낸다는 것
Godot 게임을 웹으로 내보내면, 게임 엔진 자체가 WebAssembly(줄여서 wasm)라는 형태로 바뀌어 브라우저 안에서 돕니다. WebAssembly는 브라우저가 빠르게 실행할 수 있는 프로그램 꼴입니다. 집에서 쓰던 주방(Windows)을 통째로 푸드 트럭(브라우저)에 옮겨 싣는 것과 비슷합니다. 요리(게임)는 같지만, 트럭에 맞게 바뀌는 것이 생깁니다.
| 바뀌는 것 | 데스크톱 판 | 웹 판 |
|---|---|---|
| 화면 그리는 방식(렌더러) | Forward+ 등 고를 수 있음 | Compatibility만(WebGL 2.0) |
| 스레드 | 여러 개 | 4.3부터 기본은 하나 |
| 운영체제 글꼴 | 빌려 쓸 수 있음 | 못 씀 |
| 파일 | 실행 파일 하나 | html·js·wasm·pck 등 여러 개 |
| 여는 법 | 더블클릭 | 웹 서버를 거쳐 브라우저로 |
아래 절은 이 표의 줄을 하나씩 다룹니다.
2. 내보내기 템플릿 준비
내보내기 템플릿(export template)은 플랫폼마다 미리 만들어 둔 엔진 판입니다. 내보내기는 이 템플릿에 우리 게임 데이터를 붙이는 일입니다. 빈 도시락통(템플릿)에 반찬(게임)을 담는 것과 같습니다. 그래서 템플릿이 없으면 내보내기 단추가 막힙니다.
따라 하기(공식 문서 기준):
- Godot 편집기에서 Editor ‣ Manage Export Templates를 엽니다.
- 지금 쓰는 판(예: 4.7.2.stable)에 맞는 템플릿을 받아 설치합니다. 편집기 판과 템플릿 판이 정확히 같아야 합니다.
템플릿 묶음에는 Windows, macOS, Linux, Android, iOS, 웹 판이 모두 들어 있어 큽니다. 협곡 돌파를 만들 때 받은 묶음은 1.2 GB였습니다. 그 가운데 Windows와 웹 판만 꺼내 템플릿 폴더(%APPDATA%\Godot\export_templates\4.7.2.stable\)에 넣어도 두 플랫폼 내보내기는 됐습니다. 디스크가 넉넉하면 편집기 창에서 받는 것이 가장 쉽습니다.
3. 렌더러와 스레드 설정
렌더러는 3D 장면을 화면 그림으로 바꾸는 엔진의 화가입니다. Godot에는 Forward+, Mobile, Compatibility 세 화가가 있는데, 웹에서 일할 수 있는 화가는 Compatibility 하나뿐입니다. 공식 문서는 웹 플랫폼이 WebGL 2.0을 쓰고 Forward+와 Mobile은 지원하지 않는다고 적습니다.
데스크톱용으로 Forward+를 쓰는 프로젝트도 웹으로 내보낼 수 있습니다. 프로젝트 설정에 웹 전용 렌더러를 따로 두면 됩니다. 협곡 돌파의 project.godot에는 이렇게 적혀 있습니다.
renderer/rendering_method="forward_plus"
renderer/rendering_method.web="gl_compatibility"
첫 줄은 데스크톱, 둘째 줄은 웹에서 쓸 렌더러입니다. 화가가 바뀌니 그림이 조금 달라집니다. 그림자, 빛 번짐, 안개 같은 효과가 데스크톱 판과 다르게 보일 수 있으니, 웹 판은 꼭 따로 열어 확인하세요.
스레드는 프로그램 안에서 동시에 일하는 일꾼 수입니다. 웹 판은 Godot 4.3부터 일꾼 하나(단일 스레드)가 기본입니다. 여러 일꾼(Thread Support 켬)을 쓰려면 게임을 올리는 서버가 아래 두 응답 머리글을 보내야 하고, 보안 연결(https)도 필요합니다.
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
서버 설정을 바꿀 수 없는 곳에 올린다면 기본값(꺼짐)을 그대로 두는 것이 안전합니다. 협곡 돌파도 꺼 둔 채(variant/thread_support=false) 내보냈습니다.
4. 내보내기와 나온 파일
따라 하기(편집기 단계는 공식 문서 기준):
- Project ‣ **Export…**를 엽니다.
- **Add…**에서 Web을 골라 웹 프리셋을 만듭니다.
- Export Path에
index.html로 끝나는 경로를 적습니다. 웹 판은 파일이 여러 개 나오므로 빈 폴더를 하나 만들어 그 안을 가리키세요. - Export Project를 누릅니다.
같은 일을 명령줄로도 할 수 있습니다. 협곡 돌파는 아래처럼 편집기 창 없이 내보냈습니다. 프리셋 이름 "Web"은 2단계에서 만든 이름입니다.
Godot_v4.7.2-stable_win64_console.exe --headless --path game\topgun_flight --export-release "Web"
나온 폴더에는 아래 파일들이 생깁니다.
| 파일 | 하는 일 | 크기 |
|---|---|---|
index.html | 게임을 띄우는 웹 페이지 | 5 KB |
index.js | 엔진을 불러오는 시작 스크립트 | 0.28 MB |
index.wasm | 엔진 본체(WebAssembly) | 39.5 MB |
index.pck | 우리 게임 데이터(장면·모델·소리·글꼴) | 2.84 MB |
index.png 등 | 시작 그림, 아이콘, 소리 처리 스크립트 | 합쳐 약 0.05 MB |
그림 2. 협곡 돌파 웹 판의 파일 크기. 엔진 본체(wasm)가 대부분을 차지합니다 (도표)
눈여겨볼 점은 게임 데이터는 2.84 MB인데 엔진 본체가 39.5 MB라는 것입니다. 게임을 작게 만들어도 웹 판은 40 MB 가까이 됩니다. 엔진 전체가 함께 실려 가기 때문입니다.
5. 파일 크기 줄이기: 서버 압축
이 크기는 서버 압축으로 크게 줄어듭니다. 공식 문서는 gzip 압축이 WebAssembly 파일을 4분의 1쯤으로 줄인다고 안내합니다. 협곡 돌파의 index.wasm을 gzip(최고 압축)으로 줄여 보니 39.5 MB가 10.1 MB가 됐습니다. 4분의 1과 거의 같습니다. 반면 index.pck는 2.84 MB가 2.77 MB로 조금만 줄었습니다. 그림과 소리처럼 이미 압축된 데이터가 많아서입니다.
압축은 우리가 파일을 바꾸는 것이 아니라 올리는 곳이 해 줘야 합니다. 이삿짐을 진공 팩에 넣어 보내는 것처럼, 서버가 줄여 보내고 브라우저가 받아서 풉니다. 공식 문서의 호스팅 안내를 보면 GitHub Pages는 보낼 때 알아서 압축하고, itch.io는 압축하지 않습니다. 올릴 곳을 고를 때 이 차이를 보세요. 압축하지 않는 곳이면 처음 여는 사람이 40 MB를 그대로 받아야 합니다.
6. 한글 글꼴 넣기
웹 판에서 가장 흔히 놀라는 곳이 한글이 네모(□)로 나오는 것입니다. 까닭은 이렇습니다.
- Godot의 기본 글꼴에는 한글 글자가 없습니다.
- 데스크톱 판은 엔진이 운영체제의 글꼴을 대신 빌려 와서 한글을 보여 줍니다. 공식 문서는 이 기능으로 한중일 글자와 이모지를 따로 글꼴 없이 보여 줄 수 있다고 적습니다.
- 그런데 운영체제 글꼴을 불러오는 기능은 Windows, macOS, Linux, Android, iOS에서만 됩니다. 웹은 목록에 없습니다.
그래서 데스크톱에서 잘 보이던 한글이 웹에서만 깨집니다. 빌려 쓸 이웃(운영체제)이 없으니, 글꼴을 게임 안에 직접 넣어야 합니다.
협곡 돌파는 무료 글꼴 Noto Sans KR Bold에서 자주 쓰는 한글 2,350자만 뽑아 424 KB짜리 글꼴 파일로 만들어 넣었습니다. 한글 전체를 담은 글꼴은 몇 MB가 되니, 쓰는 글자만 남기면 index.pck가 덜 커집니다. Noto Sans KR은 OFL(SIL Open Font License)이라 게임에 넣어 배포할 수 있습니다. 다른 글꼴을 쓸 때는 라이선스에 게임 안 배포가 허락되는지 먼저 보세요.
글꼴을 넣은 뒤에는 프로젝트 설정의 기본 글꼴이나 테마에 그 글꼴을 지정해, 모든 글자 칸이 그 글꼴을 쓰게 합니다. 그림 1의 제목과 조작 안내가 브라우저에서 깨지지 않고 나온 것이 이 덕분입니다.
7. 내 PC에서 브라우저로 시험하기
내보낸 index.html을 더블클릭해 열면 게임이 뜨지 않습니다. 웹 판은 웹 서버를 거쳐 열어야 합니다. 브라우저가 내 PC의 파일을 바로 열 때는 보안 때문에 wasm 같은 파일을 불러오는 일을 막기 때문입니다. 가게(서버) 계산대를 거쳐야 물건을 내주는 것과 같습니다.
따라 하기:
-
Node.js가 깔린 PC라면, 내보낸 폴더에서 명령 창을 열고 아래를 입력합니다. 작은 시험용 서버가 뜹니다.
npx http-server -p 4310 -c-1-p 4310은 주소의 번호(포트),-c-1은 브라우저가 옛 파일을 기억해 두지 않게 하는 값입니다. 다시 내보낸 뒤 바뀐 판이 바로 보입니다. -
브라우저에서
http://127.0.0.1:4310/index.html을 엽니다. -
처음에는 40 MB 가까운 파일을 받느라 시간이 걸립니다. 그림 1 같은 처음 화면이 나오면 성공입니다.
서버를 띄우는 다른 방법도 있습니다. 편집기의 내보내기 프리셋에서 Runnable을 켜 두면 편집기 오른쪽 위의 원격 실행 단추로 바로 브라우저 시험을 할 수 있다고 공식 문서는 안내합니다. 실제로 사람들에게 공개할 때는 시험용 서버가 아니라 정식 웹 호스팅(itch.io, GitHub Pages 같은 곳)에 올리세요.
브라우저 개발자 도구(F12)의 Console 탭을 열면 엔진이 시작하며 남긴 줄이 보입니다. 그림 1·3을 찍은 환경(화면 없이 띄운 Chromium)에서 협곡 돌파를 열었을 때는 이런 줄이 나왔습니다.
Godot Engine v4.7.2.stable.official
OpenGL API OpenGL ES 3.0 (WebGL 2.0 (OpenGL ES 3.0 Chromium)) - Compatibility
Build configuration: Emscripten 4.0.20, single-threaded, no GDExtension support.
둘째 줄에서 Compatibility 렌더러(3절), 셋째 줄에서 단일 스레드(3절)로 돈다는 것을 확인할 수 있습니다. 화면이 안 뜰 때도 이 탭에 원인이 빨간 글자로 나오니 먼저 보세요.
그림 3. 처음 화면에서 Enter를 누른 뒤 조종하지 않고 두었을 때. 실패 안내 글자와 속도·고도 막대 같은 화면 표시가 웹 판에서도 그대로 나옵니다 (브라우저 화면 캡처)
8. 올리기 전에 확인할 것
| 확인할 것 | 까닭 |
|---|---|
| 웹 판을 직접 열어 한 판 끝까지 해 보기 | 렌더러가 달라 보이는 모습과 속도가 데스크톱과 다름 |
| 한글이 모두 보이는지 | 운영체제 글꼴을 못 빌림(6절) |
| 처음 받는 크기 | 압축 없이 40 MB 가까움. 올릴 곳의 압축 여부 확인(5절) |
| 느린 PC·노트북에서 한 번 | 협곡 돌파도 웹 판에서 끊김(렉)이 있다는 의견이 있었음 |
| 소리 | 브라우저는 사용자가 한 번 누르기 전에는 소리를 막는 경우가 많음. 처음 화면에서 키를 누르게 하면 자연스러움 |
협곡 돌파의 웹 판은 한글은 깨지지 않았지만 데스크톱 판보다 끊김이 있었습니다. 원인은 아직 따로 재지 않았습니다. 짐작 가는 곳은 렌더러가 바뀐 것, 먼 거리까지 그리는 그림자, 프레임마다 다시 그리는 화면 표시 같은 것들이라, 웹 판에서는 그림자 거리와 효과를 줄인 설정을 따로 두는 것이 다음 할 일입니다. 웹으로 낼 게임이라면 처음부터 가벼운 장면으로 계획하세요. 게임 범위를 작게 잡는 법은 첫 게임 범위 정하기에 있습니다.
연습 문제
- 여러분 프로젝트의
project.godot를 메모장으로 열어rendering_method가 몇 줄 있는지, 웹 전용 줄이 있는지 적어 보세요. - 웹으로 내보낸 폴더에서 가장 큰 파일과 두 번째로 큰 파일이 무엇인지 확인합니다.
- 글자 칸 하나에 한글을 넣고 웹으로 내보내, 글꼴을 넣기 전과 뒤에 어떻게 보이는지 견주어 보세요.
자주 하는 실수와 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| Export Project 단추가 눌리지 않는다 | 내보내기 템플릿이 없거나 판이 다름 | Manage Export Templates에서 편집기와 같은 판 설치 |
| index.html을 열면 아무것도 안 뜬다 | 파일을 직접 열었음 | 작은 웹 서버를 띄워 http:// 주소로 열기(7절) |
| 한글이 네모로 나온다 | 웹은 운영체제 글꼴을 못 빌림 | 한글 글꼴을 게임에 넣고 기본 글꼴로 지정(6절) |
| 데스크톱과 그림이 다르다 | 웹은 Compatibility 렌더러 | 웹 판을 따로 보고 효과를 맞춤(3절) |
| 스레드를 켰더니 게임이 안 뜬다 | 서버가 COOP·COEP 머리글을 안 보냄 | 스레드를 끄거나, 머리글을 보내는 곳에 올림(3절) |
| 처음 여는 데 너무 오래 걸린다 | 40 MB를 압축 없이 받음 | 압축해 주는 곳에 올리기(5절) |
한 줄 정리
템플릿은 편집기와 같은 판, 웹은 Compatibility·단일 스레드, 엔진 본체가 40 MB라 압축하는 곳에, 한글 글꼴은 게임 안에, 시험은 작은 서버로.
Blender에서 만든 모델을 Godot로 옮기는 법은 Blender 모델을 Godot로 옮기기에, 1인 개발 전체 흐름은 1인 게임 개발 지도에 있습니다.
참고 자료
- Godot 4.7 문서, Exporting for the Web(렌더러, 스레드와 COOP·COEP, 내보낸 파일, 압축, 호스팅): https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html
- Godot 4.7 문서, Using fonts(시스템 글꼴 대신 보여 주기, 지원 플랫폼): https://docs.godotengine.org/en/stable/tutorials/ui/gui_using_fonts.html
- Godot 4.7 문서, Exporting projects(내보내기 템플릿): https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html
- Noto Sans KR(SIL Open Font License): https://fonts.google.com/noto/specimen/Noto+Sans+KR
- 그림 라이선스: 그림 1·3은 직접 만든 게임의 브라우저 화면, 그림 2는 내보낸 파일 크기를 옮긴 도표입니다.
