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), UnityUnityTheme(.uss, ScriptableObject.asset), UnrealUnrealTheme(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이 존재하기 전에 빌드하지 않으며, 초안에서 빌드하지도 않습니다.- 프리뷰에 필요한 것이 킷에 없으면, 한 페이지가 아닌 킷에 추가합니다.