32-example-webgl-server — Unity WebGL 서버 가이드
Status: ACTIVE AppliesTo: v10 Type: GUIDE
Scope
UnityExample WebGL 빌드 → NestJS(WebGLServer)로 로컬 서빙 → 브라우저 스모크 테스트
SSOT Paths
| 구분 | 경로 |
|---|---|
| Unity project | framework-cs/apps/UnityExample/ |
| WebGL build output (default) | output/unity-webgl/UnityExample/ |
| NestJS server app | framework-ts/apps/WebGLServer/ |
| 환경변수 정의 (SSOT) | framework-ts/apps/WebGLServer/env.spec.json |
| .env.example (자동 생성) | framework-ts/apps/WebGLServer/.env.example |
Build Steps (Unity)
- Unity Editor에서
framework-cs/apps/UnityExample프로젝트 열기 - File → Build Settings
- Platform: WebGL 선택 → Switch Platform
- Development Build: On (스모크 테스트 동안)
- Build 클릭 → 출력 경로:
output/unity-webgl/UnityExample/
Run Steps
Step 1: (권장) GameServer 실행
cd framework-ts
npm ci
npm -w game-server run start
Step 2: WebGL 정적 서버 실행
cd framework-ts
npm -w webgl-server run start:dev
Step 3: 브라우저 접속
http://localhost:8081/
Environment Variables
SSOT:
env.spec.json→.env.example는 자동 생성 (수동 편집 금지)환경변수 변경 시:
env.spec.json수정 →npm -w webgl-server run env:sync
| 변수 | 기본값 | 설명 |
|---|---|---|
WEBGL_ROOT | output/unity-webgl/UnityExample | WebGL 빌드 출력 경로 |
WEBGL_PORT | 8081 | 서버 포트 (1..65535) |
# .env.example 생성/갱신
npm -w webgl-server run env:sync
# 기본 실행
cd framework-ts
npm -w webgl-server run start:dev
# 포트 지정
cd framework-ts
WEBGL_PORT=8091 npm -w webgl-server run start:dev
# 루트+포트 지정
cd framework-ts
WEBGL_ROOT=output/unity-webgl/UnityExample WEBGL_PORT=8091 npm -w webgl-server run start:dev
Smoke Checklist
| 항목 | 확인 |
|---|---|
| 로딩/씬 진입 OK | [ ] |
console error 0 (특히 .jslib not found, undefined symbol, Module.*, ERR_*) | [ ] |
| (권장) WS 연결 성공 (서버 로그 + 브라우저 로그) | [ ] |
DoD (Definition of Done)
- WebGL 로딩 성공, 씬 진입
- 브라우저 콘솔 치명 에러 0
-
WEBGL_PORT설정 시 해당 포트로 기동 확인 - (권장) WS 연결 확인:
- 서버 로그에 connect 흔적
- 브라우저에서 연결 성공 로그 또는 게임 UI에 연결 표시
Hard Rules
- WebGL은 반드시 HTTP 서버로 서빙한다 (파일 직접 열기 금지)
- 로컬 서빙은 NestJS(WebGLServer)를 표준으로 사용한다
- DoD는 "빌드 성공"이 아니라 브라우저 로드 + 콘솔 에러 0까지 포함한다
Server Features
- Port:
WEBGL_PORT(기본값 8081) - Static serving:
WEBGL_ROOT폴더 정적 서빙 - SPA fallback: 정적 파일 없으면
index.html로 fallback - MIME types:
.wasm,.data,.gz,.br헤더 자동 설정 - Validation:
index.html없으면 명확한 에러 메시지 후 종료
Related
- 30-example-network-server — Game Protocol TS 서버 예제
- 31-example-network-client — Game Protocol TS 클라이언트 예제
- 03-ssot — Example Apps SSOT
- 30-env-management — 환경변수 관리 정책