Communitygithub.com

UI 프리뷰

게임 프로젝트에서 HUD 요소, 메뉴, 프롬프트, 전환 효과 또는 화면 효과를 엔진에서 구현하기 전에 조정 가능한 HTML 프리뷰를 만들고, 사용자가 조정한 값을 빌드 사양으로 전환합니다. 프리뷰는 게임 해상도로 실제 게임 스크린샷 위에 그려지며, 슬라이더, 색상, 변형, 상태를 포함한 조정 패널, 라이브 디스크 저장, 승인된 values.json을 저장하는 Save 버튼, 모든 상태를 보여주는 검토 시트, 그리고 승인된 값을 Godot이나 Unity에 작성하는 스크립트를 갖추고 있습니다. 게임 UI나 시각 효과의 디자인, 모형, 재스타일링, 미세 조정을 요청하거나, 작은 변경 사항이라도 조정할 수 있는 프리뷰나 모형을 요청할 때 사용합니다.

UI 프리뷰란 무엇인가요?

UI 프리뷰는 게임 개발에서 UI 요소나 시각 효과를 엔진에 직접 구현하기 전에 HTML 기반의 조정 가능한 프리뷰를 통해 디자인과 사양을 확정하는 워크플로우입니다. 이 기술은 실제 게임 스크린샷 위에 HUD, 메뉴, 전환 효과 등을 그려주며, 슬라이더와 색상 선택기 등으로 실시간 조정이 가능합니다. 모든 조정 값은 `values.json` 파일로 저장되어 빌드 사양이 되며, Godot, Unity, Unreal 엔진에 자동 적용하는 파이썬 스크립트를 제공합니다. 또한 각 변형과 상태를 캡처한 검토 시트를 생성하여 팀원들과 시각적으로 논의할 수 있으며, 최종 승인 후에만 엔진에 구현하는 규칙을 통해 불필요한 반복 작업을 줄이고 일관된 UI 디자인을 유지합니다. Claude Code, Cursor, Codex와 같은 AI 에이전트에서 게임 UI 변경 요청이 들어왔을 때 이 스킬을 활용하여 디자인-빌드 피드백 루프를 획기적으로 단축할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomas-ratz/game-ui-proof/tree/HEAD/skills/ui-preview

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

UI 프리뷰은(는) 무엇을 하나요?

게임 UI의 모양을 바꾸는 작업은 반드시 HTML 프리뷰를 조정하고 Save를 누른 후에만 진행합니다. 저장된 values.json이 사양입니다. 모든 숫자는 에디터에 노출된 프로퍼티나 테마 항목이 되며, 코드에 매직 넘버로 남지 않습니다. 아무도 볼 수 없는 변경은 프리뷰가 필요 없습니다.

작업 순서: 프리뷰할 대상 → 해당 위치의 스크린샷 → 프리뷰 페이지 → 검토 시트 → 조정 후 Save → values.json에서 빌드 → 빌드-프리뷰 비교 시트.

1. 설정 (프로젝트당 한 번)

  • assets/kit/을 docs/mockups/kit/으로 복사합니다. (다른 폴더도 가능: 스크립트에 --mockups 전달). 사용하지 않는 엔진별 파일은 생략 가능: godot_theme.js + apply_godot.py (Godot), unity_theme.js + apply_uss.py (Unity), unreal_theme.js + apply_unreal.py (Unreal). Godot: assets/godot/project.js도 kit/에 복사하고 내용을 채웁니다(폰트, 키 글리프). Godot 페이지는 여기서 로드합니다.
  • project.css는 편집해야 할 유일한 킷 파일입니다: 게임의 폰트(@font-face)와 패널 팔레트, --display를 포함합니다. kit.js는 그리기 전에 선언된 모든 폰트를 로드합니다.
  • 프리뷰를 엔진의 임포트에서 제외하고(Godot: docs/mockups/에 빈 .gdignore 파일), docs/mockups/*/values.draft.json과 docs/mockups/*/shots/를 .gitignore에 추가합니다.
  • 프로젝트 루트를 서빙합니다: python docs/mockups/kit/serve.py (stdlib만 사용), 그런 다음 http://127.0.0.1:8765/docs/mockups/<feature>/를 엽니다. 페이지는 상대 경로로 게임 아트를 로드하고 조정 내용을 디스크에 저장합니다(§5).
  • 프로젝트 자체 스타일을 패널로 가져오기: Godot GodotTheme (테마 .tres), Unity UnityTheme (.uss, ScriptableObject .asset), Unreal UnrealTheme (C++ 클래스 기본값, Default*.ini, DataTable을 JSON/CSV로 내보내기). references/engines.md 참조; 각각 assets/<engine>/에 예제 페이지가 있습니다.

2. 질문하고 실제 배경 얻기

  • 어떤 화면, 요소 또는 효과인지, 어떤 상황인지 명확하지 않으면 질문합니다.
  • UI를 숨기고 게임 뷰포트 크기(프로젝트 해상도 설정, 매니페스트의 stage)로 해당 위치를 스크린샷하고, 오늘의 UI가 표시된 기준선 스크린샷도 하나 찍습니다. 엔진이 실행하는 작은 스크립트를 사용하고(Godot 템플릿: assets/godot/game_shots.gd; 기타: references/engines.md), 빌드 확인을 위해 프리뷰 옆에 보관합니다.
  • 스크립트로 해당 위치를 찍을 수 없는 경우에만 스크린샷을 요청합니다. 아직 찍을 것이 없는 새로운 것이나 엔진을 실행할 수 없는 경우, 평범하거나 모의 배경을 사용하고 상태 캡션에 그렇게 명시합니다.

3. 페이지 작성

assets/template/ (또는 assets/<engine>/)을 docs/mockups/<feature>/로 복사합니다. 페이지 형식, 패널 사양, Kit.spec 및 URL 매개변수는 references/kit.md에 있습니다.

  • manifest.json: 제목, stage ([w, h]), states (플레이어가 볼 수 있는 상황마다 하나씩: 비어 있음, 가득 참, 포커스됨, 비활성화됨, 가장 긴 텍스트, 애니메이션 중간; 각각 캡션과 shotTime 포함), variants (실제 선택지가 있을 때 2~4개, 각각 이름과 설명 포함), recommend (변형과 이유를 한두 줄로).
  • index.html: Kit.start({ feature, images, groups, variants, draw }). 값이 6개를 넘는 그룹은 section을 사용하여 패널이 접힐 수 있도록 합니다. 각 그룹은 엔진에서 값이 위치할 곳(스크립트 클래스, 테마 타입, 셰이더)이며, 각 키는 빌드에서 사용할 프로퍼티 이름(엔진 단위)입니다. draw(ctx, values, s)는 s.t의 순수 함수여야 합니다(t % length로 애니메이션 루프).
  • 게임 자체의 모습을 근사치가 아닌 정확히 사용: 폰트와 크기, 테마 색상(새로운 색상은 제안임: 어떤 팔레트에 추가될지 명시), 상대 경로의 실제 아트, 실제 텍스트와 숫자, 실제로 바인딩된 키를 보여주는 프롬프트.
  • 픽셀 아트: 전체 픽셀, 스무딩 없음(킷의 기본값).
  • 모션은 실제 지속 시간과 이징으로 실행됩니다. 흔들리거나, 떠다니거나, 깜빡이거나, 번쩍이는 모든 것에 대해 preview: true 그룹에서 Reduce Motion / Reduce Flashing 토글을 제공하여 해당 설정이 어떻게 바뀌는지 보여줍니다.
  • 기존 것을 조정할 때, 변형 a는 오늘날의 모습을 정확히 다시 그립니다. 기준선 스크립샷과 일치하는지 확인하고, 그렇지 않으면 다른 모든 변형이 잘못된 기준선과 비교됩니다.
  • 여러 프리뷰가 그리는 것은 킷의 공유 파일에 넣고 페이지별로 복사하지 않습니다.

4. 검토 시트

  • python docs/mockups/kit/shots.py <feature> (Chrome, Edge 또는 Chromium과 Pillow ≥ 10.1 필요)는 shots/<variant>_<state>.png를 작성하고 sheet.png를 이어붙입니다. 저장된 values.json을 사용하여 변형을 렌더링하며(--defaults는 페이지 기본값 사용), 페이지가 실패하면 0이 아닌 종료 코드를 반환하고 오류를 해당 샷에 그립니다.
  • 시트를 보여주기 전에 살펴보고, 결정할 부분을 2배로 자릅니다: 잘리거나 겹치는 텍스트, 잘못된 폰트, 무대 밖의 요소, 지루한 순간에 멈춘 애니메이션(shotTime 이동).
  • 시트, 라이브 URL 및 결정 사항을 권장 사항과 함께 보냅니다.

5. 조정 결과 읽기

  • 조정 중에는 모든 변경 사항이 <feature>/values.draft.json에 기록됩니다. 조정 결과에 대해 질문이 있을 때마다 읽되, 절대 이 파일로 빌드하지 마십시오.
  • Save (또는 Ctrl/Cmd+S)는 <feature>/values.json, 승인된 사양을 기록합니다. 페이지는 이 파일을 기반으로 열리고, 다른 행은 표시되며, ↺는 하나의 값을 되돌리고, Reset은 모든 값을 되돌립니다. 프리뷰 전용 값은 표시되거나 저장되지 않습니다.
  • serve.py가 없으면 조정 내용은 브라우저에만 저장됩니다: Save는 JSON을 복사하고(해당 브라우저의 기본값으로 유지), 사용자가 채팅에 붙여넣으면 values.json으로 저장합니다.
  • 형식: {"feature", "variant", "values": {Group: {Key: value}}}; 프리뷰 전용 그룹은 제외됩니다.

6. 사양에서 빌드

  • Godot: python docs/mockups/kit/apply_godot.py <feature>는 사양이 테마 .tres와 각 그룹이 명명하는 스크립트의 [Export] / @export 기본값, <name>.gdshader 그룹의 유니폼 기본값, 아직 export가 없는 키, 이러한 프로퍼티를 오버라이드하는 씬에서 변경하는 내용을 나열합니다. --write는 적용합니다.
  • Unity: python docs/mockups/kit/apply_uss.py <feature>는 USS 커스텀 프로퍼티(uss: 그룹)에 대해 동일하게 수행합니다. ScriptableObject 값은 수동으로 적용합니다.
  • Unreal: python docs/mockups/kit/apply_unreal.py <feature>는 각 그룹의 C++ 클래스에서 사양이 변경하는 내용을 나열합니다: Config 클래스의 Config/Default<Config>.ini 오버라이드(--target header는 선언의 기본값을 다시 작성), 아직 UPROPERTY가 없는 키(붙여넣을 선언과 함께), 수동으로 설정할 기본값. --write는 적용합니다. DataTable 값은 편집된 내보내기를 다시 가져와서 적용합니다.
  • 아직 존재하지 않는 것을 빌드합니다: 엔진의 테마 또는 스타일 시스템의 색상, 폰트 및 패널; JSON과 같이 그룹화되고 승인된 값을 기본값으로 하는 에디터 노출 프로퍼티의 크기, 오프셋, 지속 시간 및 강도.
  • 실행 중인 게임에서 확인: 프리뷰의 각 상태를 스크린샷하고 <feature>/build_vs_preview.png를 만듭니다(게임 스크린샷 옆에 프리뷰 스크린샷). 다른 부분을 수정합니다. 확인하지 않은 것을 명시합니다. 브라우저와 엔진의 텍스트 안티앨리어싱이 다르므로 위치와 크기만 판단하고 픽셀 가장자리는 무시합니다.
  • 승인된 모습에 대한 이후 변경은 새로운 라운드입니다: 프리뷰, 시트, Save, 빌드.

규칙

  • 프리뷰는 리포지토리에 남습니다: UI가 왜 그렇게 보이는지 기록합니다. sheet.png와 values.json을 커밋합니다. shots/와 초안은 재생성됩니다.
  • values.json이 존재하기 전에 빌드하지 않으며, 초안에서 빌드하지도 않습니다.
  • 프리뷰에 필요한 것이 킷에 없으면, 한 페이지가 아닌 킷에 추가합니다.

관련 스킬