unity-mcp-ui-layout

# Unity MCP UI Layout

Reusable Unity UI workflow rules for unity-mcp, packaged first as a Codex skill and then adapted for other LLM platforms.

unity-mcp를 사용할 때 Unity UI를 더 안정적으로 만들기 위한 워크플로 규칙 모음입니다. 기본 형태는 Codex 스킬이며, 다른 LLM 플랫폼에서도 사용할 수 있도록 확장되어 있습니다.

The repository is built around one core idea: when an LLM creates Unity UI from a mockup, screenshot, or target resolution, it should work from anchors, parent containers, scaling rules, and verification loops instead of raw pixel placement.

이 저장소의 핵심 아이디어는 하나입니다. LLM이 목업, 스크린샷, 목표 해상도를 바탕으로 Unity UI를 만들 때, 절대 픽셀값이 아니라 앵커, 부모 컨테이너, 스케일링 규칙, 검증 루프를 기준으로 작업해야 한다는 점입니다.

It also assumes three practical defaults: group the top-level composition by anchor-owned regions first, turn repeated structures into reusable prefabs or reusable layout blocks, and keep likely single-image resources intact unless runtime behavior requires them to be split.

또한 세 가지 실무 기본값을 전제로 합니다. 최상단 구성을 먼저 앵커 기준 영역으로 그룹화하고, 반복 구조는 재사용 가능한 프리팹 또는 레이아웃 블록으로 만들며, 단일 이미지 리소스로 보이는 영역은 런타임 동작상 분리가 필요할 때만 쪼갭니다.

Quick Rules / 빠른 작업 기준

• Group the top-level layout by anchor-owned regions before tuning leaf widgets.

• Turn repeated UI structures into reusable prefabs or reusable layout blocks.

• Keep likely single-image regions intact unless interaction, animation, or adaptive behavior requires decomposition.

• Verify structure with screenshots instead of chasing raw pixel alignment.

• leaf widget를 만지기 전에 최상단 레이아웃을 먼저 anchor 기준 영역으로 그룹화합니다.

• 반복되는 UI 구조는 재사용 가능한 프리팹 또는 레이아웃 블록으로 만듭니다.

• 단일 이미지 리소스로 보이는 영역은 상호작용, 애니메이션, 적응형 동작이 필요할 때만 분해합니다.

• raw pixel 정렬을 쫓기보다 스크린샷으로 구조를 검증합니다.

Default Platform / 기본 플랫폼

The default platform is Codex.

기본 플랫폼은 Codex입니다.

The canonical skill lives in:

정본 스킬은 아래 경로에 있습니다.

• unity-mcp-ui-layout/

Platform-specific adapters live in:

플랫폼별 어댑터는 아래 경로에 있습니다.

• Platform/

What This Helps With / 해결하려는 문제

• image-to-layout translation

• UGUI anchors and CanvasScaler

• HUD, inventory, popup, and mobile safe-area layout rules

• prefab promotion rules for repeated UI structures

• reuse/variant/new-base decision rules for existing prefabs

• prefab variant rules for controlled divergence from a shared base

• sprite/image vs RawImage rules for static versus texture-driven UI assets

• mockup-native resolution rules when a design image exists

• mockup decomposition rules for deciding what should stay baked, what should split, and what should become reusable blocks

• repair mode vs greenfield build mode rules for existing-screen fixes versus new UI creation

• asset discovery priority rules for prefab, sprite, font, material, and placeholder reuse order

• asset naming and folder rules so reusable assets stay discoverable and screen-owned assets stay scoped correctly

• text layout rules for wrapping, truncation, auto-size discipline, counters, and localization headroom

• safe-area remapping rules for mobile mockups that do not visibly account for notches or home indicators

• shared asset edit safety rules for deciding when direct base edits are too risky

• UI Toolkit container ownership, flex stability, and text overflow guidance

• concrete MCP call recipes for common UI tasks

• common failure patterns and recovery guidance

• final review checks before calling a UI task done

• screenshot verification loops

• safer unity-mcp prompting across different LLM products

• 이미지 기반 레이아웃 해석

• UGUI 앵커와 CanvasScaler 설정

• HUD, 인벤토리, 팝업, 모바일 safe area 레이아웃 규칙

• 반복되는 UI 구조를 프리팹으로 승격하는 규칙

• 기존 프리팹을 재사용/Variant/신규 생성 중 무엇으로 갈지 판단하는 규칙

• 공용 base에서 안전하게 분기하는 Prefab Variant 규칙

• 정적 UI 자산에서 sprite/image와 RawImage를 어떻게 구분할지에 대한 규칙

• 시안 이미지가 있을 때 시안의 원본 해상도를 기준 프레임으로 삼는 규칙

• 시안 요소를 어디까지 분해하고 어디를 단일 자산이나 재사용 블록으로 유지할지에 대한 규칙

• 기존 UI 수정 요청과 신규 UI 생성 요청을 구분하는 작업 모드 규칙

• 프리팹, 스프라이트, 폰트, 머티리얼, 플레이스홀더를 어떤 순서로 찾을지에 대한 자산 탐색 우선순위 규칙

• 재사용 자산은 다시 찾기 쉽고 화면 전용 자산은 범위가 드러나도록 만드는 자산 네이밍/폴더 규칙

• 줄바꿈, truncation, auto-size 절제, 숫자 영역, 지역화 여유를 위한 텍스트 레이아웃 규칙

• 노치/홈 인디케이터가 없는 시안을 모바일 safe area 안쪽 여백으로 재해석하는 규칙

• 공용 prefab/sprite/material/text style에 대한 직접 수정이 위험한지 판단하는 안전 규칙

• UI Toolkit 화면에서 container ownership, flex 안정성, text overflow를 다루는 가이드

• 자주 쓰는 UI 작업용 구체적인 MCP 호출 레시피

• 자주 실패하는 패턴과 복구 가이드

• 작업 완료 전에 보는 최종 검수 체크

• 스크린샷 기반 검증 루프

• 다양한 LLM 서비스에서 더 안전하게 unity-mcp를 쓰는 프롬프트 구성

Repository Structure / 저장소 구조

unity-mcp-ui-layout/
  SKILL.md
  agents/
  references/

Platform/
  README.md
  Codex/
    README.md
  Google-Antigravity/
    README.md
    SYSTEM_PROMPT.md
  Claude-Artifacts/
    README.md
    ARTIFACT_PROMPT.md

examples/
  README.md
  hud-example.md
  inventory-example.md
  popup-safe-area-example.md

CONTRIBUTING.md
CHANGELOG.md

Release Notes / 릴리스 노트

• CHANGELOG.md
• BACKLOG.md

Platform Notes / 플랫폼 설명

Codex

Use the skill folder directly by copying unity-mcp-ui-layout into your Codex skills directory.

unity-mcp-ui-layout 폴더를 Codex 스킬 디렉터리로 복사해서 바로 사용할 수 있습니다.

Google Antigravity

Use the prompt package in Platform/Google-Antigravity/ as the base instruction set for an Antigravity workspace or custom skill-like setup that has access to Unity through MCP or an equivalent bridge.

Platform/Google-Antigravity/의 프롬프트 패키지를 Antigravity 워크스페이스 또는 커스텀 지침에 넣어서 사용할 수 있습니다. Unity와는 MCP 또는 유사한 브리지를 통해 연결된 상태를 가정합니다.

Claude Artifacts

Use the prompt package in Platform/Claude-Artifacts/ as the base instruction for a Claude project or artifact workflow that is connected to Unity tooling.

Platform/Claude-Artifacts/의 프롬프트 패키지를 Claude 프로젝트 또는 artifact 워크플로의 기본 지침으로 사용할 수 있습니다.

Install For Codex / Codex 설치

Windows

Copy-Item -Recurse -Force .\unity-mcp-ui-layout $HOME\.codex\skills\

macOS / Linux

cp -R ./unity-mcp-ui-layout ~/.codex/skills/

Example Request / 예시 요청

Use $unity-mcp-ui-layout to build a 1920x1080 UGUI HUD from the attached layout image.
Group the top-level composition into anchor-owned regions, then translate it into parent containers and CanvasScaler rules.
Turn repeated structures into reusable prefabs or reusable layout blocks.
If a region looks like a single image resource, keep it as one image unless runtime behavior requires it to be split.
Verify the result with screenshots instead of relying on raw pixel placement.

$unity-mcp-ui-layout를 사용해서 첨부한 레이아웃 이미지를 기준으로 1920x1080 UGUI HUD를 만들어줘.
최상단 구성을 먼저 anchor 기준 영역으로 그룹화한 뒤 부모 컨테이너와 CanvasScaler 규칙으로 변환해줘.
반복 구조는 재사용 가능한 프리팹 또는 레이아웃 블록으로 만들어줘.
단일 이미지 리소스로 보이는 영역은 런타임 동작상 분리가 필요할 때만 나눠줘.
절대 픽셀 배치 대신 스크린샷 검증으로 결과를 확인해줘.

Platform Examples / 플랫폼별 예시

Codex

Use $unity-mcp-ui-layout to repair the current inventory layout in UGUI.
Preserve the style, fix slot spacing and scaling drift, and verify at 1920x1080 plus one narrower aspect ratio.
Keep repeated slot structures reusable instead of rebuilding them one by one.

$unity-mcp-ui-layout를 사용해서 현재 UGUI 인벤토리 레이아웃을 수정해줘.
기존 스타일은 유지하고, 슬롯 간격과 스케일링 드리프트를 고친 뒤
1920x1080과 더 좁은 비율 한 가지에서 검증해줘.
반복되는 슬롯 구조는 하나씩 다시 만들지 말고 재사용 가능한 형태로 유지해줘.

Google Antigravity

Build this Unity HUD from the attached mockup at 1920x1080.
Treat the image as a composition reference, group the top-level layout by anchor-owned regions, create parent regions first, and verify with screenshots.

첨부한 목업을 기준으로 1920x1080 Unity HUD를 만들어줘.
이미지는 절대 좌표 지시가 아니라 composition reference로 취급하고, 최상단 레이아웃은 anchor 기준 영역으로 먼저 그룹화해줘.
먼저 부모 영역을 만든 뒤 스크린샷으로 검증해줘.

Claude Artifacts

Using the attached mockup, help me build a 1920x1080 Unity HUD in UGUI.
Please work in an artifact-style loop with sections for Plan, Current Change, Verification, and Next Step.

첨부한 목업을 바탕으로 1920x1080 UGUI HUD를 만들 수 있게 도와줘.
Artifact 스타일로 Plan, Current Change, Verification, Next Step 섹션을 나눠서 진행해줘.

Notes / 참고

• The Codex skill is the source of truth.

• The platform folders adapt the same workflow for other LLM services.

• The examples/ folder contains practical prompt examples for common UI tasks.

• CONTRIBUTING.md explains how to extend the repo without making the skill harder to use.

• Real project usage should drive future refinements.

• Repeated UI structures should usually be documented as reusable prefabs or reusable blocks, not as repeated manual reconstruction steps.

• Decorative areas that are likely single image assets should stay simple unless interaction or adaptive behavior requires decomposition.

• Codex 스킬이 정본입니다.

• Platform/ 폴더는 같은 워크플로를 다른 LLM 서비스에 맞게 변환한 것입니다.

• examples/ 폴더에는 자주 쓰는 UI 작업용 실전 예시 프롬프트가 들어 있습니다.

• CONTRIBUTING.md에는 저장소를 확장할 때 스킬 사용성을 해치지 않도록 하는 기여 가이드가 들어 있습니다.

• 실제 프로젝트에서 사용하면서 얻는 피드백을 기준으로 계속 보완하는 것이 좋습니다.

• 반복되는 UI 구조는 수동 재구성 절차보다 재사용 가능한 프리팹 또는 블록 기준으로 문서화하는 편이 좋습니다.

• 장식 영역이 단일 이미지 에셋으로 보이면, 상호작용이나 적응형 동작이 필요할 때만 분해하는 편이 좋습니다.