22-game-server-webgl

22-game-server-webgl — 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)

1. Unity Editor에서 framework-cs/apps/UnityExample 프로젝트 열기
2. File → Build Settings
3. Platform: WebGL 선택 → Switch Platform
4. Development Build: On (스모크 테스트 동안)
5. 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

1. WebGL은 반드시 HTTP 서버로 서빙한다 (파일 직접 열기 금지)
2. 로컬 서빙은 NestJS(WebGLServer)를 표준으로 사용한다
3. 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

• 21-game-server-ts — Game Protocol TS 서버 예제
• 11-game-client-ts — Game Protocol TS 클라이언트 예제
• 03-ssot — Example Apps SSOT
• 30-env-management — 환경변수 관리 정책