67 lines
6.1 KiB
Markdown
67 lines
6.1 KiB
Markdown
---
|
||
kind: usage
|
||
title: WebGL 게임 화면 크기 등록과 실행
|
||
owner: bibimbap
|
||
stability: living
|
||
last_reviewed: 2026-10-14
|
||
---
|
||
|
||
# WebGL 화면 크기 등록과 실행
|
||
|
||
게임 등록·수정의 “화면 크기”에서 기본 선택인 “빌드에 맞추기”를 사용한다. ZIP 업로드 후 확인한 폭·높이를 안내한다. 세로·가로·정사각형 게임마다 자기 비율로 플레이 영역에 맞춰 표시된다.
|
||
|
||
크기를 확인하지 못하거나 실제 게임 화면과 다른 경우 “직접 지정”에서 게임이 기준으로 삼는 폭·높이를 입력한다. 두 값은 1~16384 정수이며 비율은 1:32~32:1이다. 미확인 상태로 자동 등록하면 기본 가로 화면(16:9)을 사용한다. 기존 게임도 수정 화면에서 다시 자동 저장하거나 직접 지정할 수 있다. 직접 지정 중 새 ZIP을 선택해도 입력한 값은 유지되므로 새 게임의 크기와 일치하는지 확인한다.
|
||
|
||
상세 화면의 “크게 보기”는 게임을 유지하면서 넓은 영역을 제공한다. “전체화면”을 사용할 수 없는 브라우저는 크게 보기로 전환한다. 닫기/Esc로 돌아오며 창 크기·화면 방향이 바뀌어도 게임의 비율을 유지한다. Unity 게임 자체가 브라우저 크기 변경을 처리하지 않는다면 내부 Canvas Scaler·앵커·카메라 설정을 개발자가 고쳐 다시 빌드해야 한다.
|
||
|
||
템플릿에 의도 크기가 없으면 진입 `index.html`과 같은 폴더에 선택적인 `build-info.json`을 넣을 수 있다. 예: `{"width":800,"height":800}`. 임의 JS로 계산한 크기를 서버가 실행하여 추론하지는 않는다. 전체 [메타 계약](../contracts/webgl-display-metadata.md)을 참고한다.
|
||
|
||
## 배포 순서
|
||
|
||
1. 대상 스키마를 지정하여 `db/migrations/20261014-game-display-metadata.sql`을 먼저 적용한다. 운영·공유 DB 변경은 해당 환경의 승인 절차를 따른다.
|
||
2. 새 WAR를 배포한다. 앱 시작 시 자동 DDL은 없다.
|
||
3. 기존 게임과 새 게임을 상세·등록·수정 화면에서 확인한다.
|
||
|
||
마이그레이션은 nullable 컬럼을 추가하고 기존 행을 백필하지 않으며 재실행 가능하다. `db/schema.sql`의 신규 DB 정의도 동일하다. 앱을 이전 버전으로 되돌릴 때 이 컬럼은 남겨도 된다. 컬럼 DROP은 별도 변경으로 다룬다. 다음 명령은 **대상 DB를 운영자가 명확히 지정한 뒤** 실행한다.
|
||
|
||
```bash
|
||
PGOPTIONS='-c search_path=dev' psql -X -v ON_ERROR_STOP=1 \
|
||
-f db/migrations/20261014-game-display-metadata.sql
|
||
```
|
||
|
||
## 자동 검증
|
||
|
||
Java 21, Node, 캐시된 Maven 의존성, Docker와 로컬 `postgres:16` 이미지가 필요하다. Maven offline cache가 없으면 의존성을 준비한 후 실행한다. 스크립트는 기존 DB/앱/볼륨을 사용하지 않고 임시 PostgreSQL을 loopback 임의 포트에 띄우며 종료 시 제거한다. 이미지를 자동 pull하지 않는다.
|
||
|
||
```bash
|
||
bash scripts/verify-webgl-display.sh all
|
||
# 개별 실행
|
||
bash scripts/verify-webgl-display.sh l1
|
||
bash scripts/verify-webgl-display.sh l2
|
||
```
|
||
|
||
macOS에서 기본 Java launcher가 런타임을 찾지 못하면 설치된 Java 21을 명시한다. 검증 환경의 Homebrew 경로 예시는 다음과 같다.
|
||
|
||
```bash
|
||
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
|
||
PATH=/opt/homebrew/opt/openjdk@21/bin:$PATH \
|
||
bash scripts/verify-webgl-display.sh all
|
||
```
|
||
|
||
L1은 Java 전체 단위·회귀, Node 플레이어 테스트, WAR 패키징이다. L2는 기존 null 행 보존, 마이그레이션 두 번 적용, CHECK 거부, fresh/migrated display 스키마 동등성 및 실제 MyBatis INSERT/UPDATE/7개 SELECT roundtrip이다. 일반 Maven test에서 격리 DB 계약 테스트는 환경변수 부재로 skip된다. harness가 만든 DB에서만 활성화하며 JDBC URL은 loopback의 `webgl_contract` DB로 제한한다.
|
||
|
||
## 격리 런타임 확인
|
||
|
||
WAR package만으로 JSP 컴파일 성공을 판단하지 않는다. 새 disposable PostgreSQL을 별도로 만들고 `db/schema.sql`을 적용한 후, 기존 앱과 겹치지 않는 포트(예: 18081)에 Maven `spring-boot:run`으로 앱을 기동한다. 현재 WAR에는 Main manifest가 없으므로 `java -jar`로 실행할 수 없다. 임시 DB 포트는 `<isolated-port>`에 지정한다. 다음은 검증에서 성공한 Java 21 실행 명령을 일반화한 예시다. macOS 외 환경에서는 설치된 Java 21 경로로 바꾼다.
|
||
|
||
```bash
|
||
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
|
||
PATH=/opt/homebrew/opt/openjdk@21/bin:$PATH \
|
||
./mvnw -o spring-boot:run \
|
||
'-Dspring-boot.run.arguments=--server.address=127.0.0.1 --server.port=18081 --spring.config.import= --spring.datasource.driver-class-name=org.postgresql.Driver --spring.datasource.url=jdbc:postgresql://127.0.0.1:<isolated-port>/webgl_contract?currentSchema=dev --spring.datasource.username=postgres --spring.datasource.password= --app.upload.game-storage-path=/tmp/bibimbap-webgl-smoke-uploads'
|
||
```
|
||
|
||
격리 DB의 임시 계정으로 로그인한 뒤 등록→업로드→저장→상세→수정 흐름을 확인한다. 실제 받은 ZIP과 별도 가로·정사각형 빌드를 각각 등록해 자기 크기가 적용되는지 본다. 직접 지정·새 ZIP 교체·기존 크기 미확인 게임도 확인한다. 등록 `/game/new`, 상세 `/game/{id}`, 수정 `/game/{id}/edit`의 응답 200과 서버의 JSP/stacktrace 오류 부재를 확인한다. 기존 원본 ZIP과 저장된 HTML의 SHA-256을 비교하여 빌드가 변하지 않았음을 남긴다.
|
||
|
||
320×844, 1440×900, 844×390, 640×300 viewport에서 세로·가로·정사각형 게임 모두 iframe이 stage 경계 안에 있고 비율 오차가 1px 이내인지 확인한다. 일반·크게 보기·전체화면 진입/복귀·API 거절 fallback·resize를 확인하며 iframe DOM/src/load 횟수와 게임 상태가 유지되는지 기록한다. 실제 Unity canvas는 CSS client 크기와 drawing buffer 크기를 각각 확인하고 상하단 UI·클릭 좌표·모바일 터치 입력을 점검한다. 콘솔 오류, focus 복귀, Esc, body 스크롤 복원도 확인한다. 확인 후 임시 앱/DB/업로드만 정리한다.
|