Unity Resource RAG

unity-resource-rag는 레퍼런스 이미지나 목업을 바탕으로, Unity 프로젝트 안의 실제 Sprite, Prefab, TMP Font Asset, Material을 우선 활용해 UI를 조립하기 위한 저장소다.

한눈에 보기

이 저장소는 크게 두 레이어로 구성된다.

Unity 내부 실행 레이어: UPM 패키지 com.hanjo92.unity-resource-rag
Unity 외부 파이프라인 레이어: planning / retrieval / verification을 담당하는 Python sidecar + MCP server

주요 구성 요소

Unity 쪽

Custom tool: index_project_resources
Custom tool: query_ui_asset_catalog
Resource: ui_asset_catalog
Custom tool: apply_ui_blueprint

Sidecar 쪽

Workflow: reference image -> resolved blueprint -> MCP handoff
Verification workflow: screenshot compare -> repair handoff
MCP server wrapper: python3 -m pipeline.mcp
Provider gateway server: python3 -m pipeline.gateway

저장소 구조

Packages/com.hanjo92.unity-resource-rag/
pipeline/
specs/
docs/
examples/

요구 사항

Python 3.11+
unity-mcp가 설치된 Unity 프로젝트
선택 사항: OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN
선택 사항: UNITY_RESOURCE_RAG_GATEWAY_URL, UNITY_RESOURCE_RAG_GATEWAY_TOKEN
또는 Codex/로컬 OAuth 로그인 상태($CODEX_HOME/auth.json 또는 ~/.codex/auth.json)

API 키가 없어도 동작은 가능하다. UNITY_RESOURCE_RAG_GATEWAY_URL이 있으면 gateway를 우선 쓸 수 있고, Codex OAuth 로그인 파일이 있으면 OpenAI provider를 그대로 쓸 수 있다. Google 쪽은 gemini(API key)와 antigravity(OAuth / gcloud access token), Anthropic 쪽은 claude(API key)와 claude_code(Claude Code bearer token / credential file)로 나눠서 사용할 수 있다. 전부 없으면 이미지 레이아웃 추출은 local_heuristic fallback을 사용한다.

설치

1) Python 설정

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2) Unity 설정

Unity 프로젝트에 unity-mcp를 설치한다.
이 저장소의 Packages/com.hanjo92.unity-resource-rag를 Packages/ 아래에 두거나 Git URL로 설치한다.
가능하면 이 저장소 전체를 local checkout으로 두고 package를 file: 경로로 연결한다. Window > Unity Resource RAG의 one-click build는 패키지 내부 코드뿐 아니라 루트 pipeline/ sidecar도 필요하다.
Unity에서 Window > Unity Resource RAG를 열고 Quick Setup을 한 번 실행한다. 이 버튼은 Unity MCP를 HTTP Local로 맞추고, Project Scoped Tools를 끄고, custom tool/resource 노출과 Codex config 동기화를 함께 시도한다.
Readiness Dashboard에서 repo / python / provider login / Unity Editor connection / build input 상태를 확인한다. Python이 막혀 있으면 같은 창에서 Bootstrap Python Runtime으로 repo-local .venv와 requirements를 준비할 수 있다.
Unity에서 discovery와 resource registration이 완료되면 index_project_resources, query_ui_asset_catalog, apply_ui_blueprint는 custom tool로, ui_asset_catalog는 MCP resource로 사용할 수 있다.
sidecar와 gateway를 같이 띄울 때는 unity-mcp의 기본 127.0.0.1:8080/mcp와 겹치지 않도록 gateway 기본 URL http://127.0.0.1:8090을 사용한다.

패키지 상세 문서는 Packages/com.hanjo92.unity-resource-rag/README.md에서 확인할 수 있다.

3) MCP 클라이언트 설정

이 저장소는 unity-mcp를 대체하지 않는다. MCP client에는 두 서버를 함께 등록해야 한다.

unity-mcp: Unity Editor를 실제로 조작
이 저장소의 MCP server: planning / retrieval / repair sidecar를 담당

대부분의 사용자는 query_ui_asset_catalog tool만 써도 된다. ui_asset_catalog는 같은 내용을 raw MCP resource로 노출하는 경로라서, resource를 잘 다루는 클라이언트에서만 직접 읽으면 된다.

실사용용 전체 예시는 examples/mcp/mcp-client-config.with-unity-mcp.example.json에 있고, key 설명은 examples/mcp/mcp-client-config.with-unity-mcp.example.md에서 볼 수 있다.

긴 설명 대신, 아래 요약표에서 본인 상황과 가장 가까운 항목을 고른 뒤 docs/mcp-client-setup.md의 선택 가이드로 바로 들어가는 것을 권장한다.

상황	바로 선택할 설정	이동
Codex에 이미 로그인되어 있다	`codex_oauth`	빠른 선택 가이드
OpenAI API 키를 이미 쓰고 있다	`openai_api_key`	추천 설정 5가지
Gemini API 키를 이미 쓰고 있다	`gemini_api_key`	추천 설정 5가지
Claude Code credential을 재사용하고 싶다	`claude_code`	추천 설정 5가지
인터넷 없이 동작만 테스트하고 싶다	`offline_local`	추천 설정 5가지

사용 시나리오별 JSON 예시는 아래 문서에서 바로 복사할 수 있다.

직접 실행할 때는 아래 둘 중 하나를 사용하면 된다.

python3 -m pipeline.mcp

python3 /absolute/path/to/unity-resource-rag/pipeline/mcp/server.py

빠른 시작

기본 흐름

Unity에서 Window > Unity Resource RAG를 열고 Quick Setup을 누른다.
같은 창의 Readiness Dashboard에서 Refresh Readiness를 눌러 현재 상태를 확인한다.
Python runtime이 막혀 있으면 Bootstrap Python Runtime을 먼저 실행한다.
reference 이미지를 넣거나, 비워둔 채 goal/title/body만 채운 뒤 Start UI Build를 누른다.
이 버튼은 내부적으로 readiness를 다시 확인한 뒤 unity_rag.start_ui_build를 호출하고, reference가 있으면 run_first_pass_ui_build, 없으면 run_catalog_draft_ui_build를 자동 선택한다.
build가 끝나면 같은 창에서 Capture Result로 현재 Unity 결과를 캡처한다.
reference build였다면 Run Repair Handoff로 mismatch report와 repair bundle을 만든다.
검토 케이스를 남기고 싶으면 Export Case Report로 md/json 리포트를 Library/ResourceRag/Cases/ 아래에 저장한다.

Unity window 기반 one-click build는 full local checkout 경로를 알아야 한다. Git URL로 패키지만 설치된 상태라면 Sidecar Repo Root에 전체 저장소 checkout 경로를 따로 지정해야 한다.

Capture Result와 Run Repair Handoff는 Unity 창 안에서 계속 이어갈 수 있다. Run Repair Handoff는 reference 이미지가 있을 때만 활성화된다.

CLI 예시

python3 pipeline/workflows/run_reference_to_resolved_blueprint.py \
  --image /absolute/path/to/reference.png \
  --catalog /absolute/path/to/resource_catalog.jsonl \
  --provider auto

Gemini preset을 바로 쓰려면:

python3 pipeline/workflows/run_reference_to_resolved_blueprint.py \
  --image /absolute/path/to/reference.png \
  --catalog /absolute/path/to/resource_catalog.jsonl \
  --provider gemini

Antigravity preset을 바로 쓰려면:

python3 pipeline/workflows/run_reference_to_resolved_blueprint.py \
  --image /absolute/path/to/reference.png \
  --catalog /absolute/path/to/resource_catalog.jsonl \
  --provider antigravity

Claude preset을 바로 쓰려면:

python3 pipeline/workflows/run_reference_to_resolved_blueprint.py \
  --image /absolute/path/to/reference.png \
  --catalog /absolute/path/to/resource_catalog.jsonl \
  --provider claude

Claude Code preset을 바로 쓰려면:

python3 pipeline/workflows/run_reference_to_resolved_blueprint.py \
  --image /absolute/path/to/reference.png \
  --catalog /absolute/path/to/resource_catalog.jsonl \
  --provider claude_code

Codex OAuth 로그인(~/.codex/auth.json)을 그대로 재사용하고 싶다면 별도 OPENAI_API_KEY 없이도 같은 명령으로 동작한다. 다른 위치의 auth 파일을 쓰려면:

python3 pipeline/workflows/run_reference_to_resolved_blueprint.py \
  --image /absolute/path/to/reference.png \
  --catalog /absolute/path/to/resource_catalog.jsonl \
  --provider openai \
  --auth-mode oauth_token \
  --codex-auth-file /custom/path/to/auth.json

MCP preset 예시

MCP tool에서는 처음 설정할 때 저수준 인증 필드를 직접 채우기보다 connection_preset을 먼저 고르는 것을 권장한다.

recommended_auto: 권장값. 가능한 인증을 자동 선택
codex_oauth: Codex OAuth로 OpenAI 연결
openai_api_key: OPENAI_API_KEY
gemini_api_key: GEMINI_API_KEY 또는 GOOGLE_API_KEY
google_oauth: GOOGLE_OAUTH_ACCESS_TOKEN 또는 gcloud access token
claude_api_key: ANTHROPIC_API_KEY
claude_code: ANTHROPIC_AUTH_TOKEN 또는 ~/.claude/.credentials.json
custom_openai_compatible: 별도 OpenAI-compatible endpoint (provider_base_url + 서비스 전용 API key)
offline_local: local_heuristic 전용

예를 들어 MCP client에서 workflow tool을 호출할 때는 다음처럼 시작하면 된다.

{
  "tool": "unity_rag.start_ui_build",
  "arguments": {
    "image": "/absolute/path/to/reference.png",
    "unity_project_path": "/absolute/path/to/unity-project",
    "connection_preset": "recommended_auto"
  }
}

reference 없이 catalog 기반 draft부터 시작하고 싶을 때도 같은 tool에 goal만 주면 된다.

{
  "tool": "unity_rag.start_ui_build",
  "arguments": {
    "goal": "reward popup",
    "screen_name": "RewardPopupDraft",
    "title": "Reward Unlocked",
    "body": "Catalog-first popup draft",
    "primary_action_label": "CLAIM",
    "secondary_action_label": "CLOSE",
    "unity_project_path": "/absolute/path/to/unity-project"
  }
}

세부 단계를 직접 지정하고 싶을 때는 아래처럼 기존 tool을 개별 호출하면 된다.

{
  "tool": "unity_rag.run_first_pass_ui_build",
  "arguments": {
    "image": "/absolute/path/to/reference.png",
    "unity_project_path": "/absolute/path/to/unity-project",
    "connection_preset": "recommended_auto"
  }
}

커스텀 endpoint가 필요할 때만 provider_base_url 같은 고급 설정을 함께 넣는다. 대부분의 사용자는 CLI든 MCP든 기본값 또는 auto/recommended_auto만으로 시작하면 된다. 세부 단계를 직접 제어하고 싶을 때만 unity_rag.run_reference_to_resolved_blueprint로 내려가면 된다.

문서 바로가기

핵심 문서

참고 자료

examples/mcp/end-to-end-usage.md

링크

Repository: Hanjo92/unity-resource-rag
Issues: github.com/Hanjo92/unity-resource-rag/issues
Releases: github.com/Hanjo92/unity-resource-rag/releases
License: LICENSE

참고 사항

생성물과 캐시는 .gitignore로 제외한다.
실제 사용 전에는 Unity 프로젝트 안에서 C# 컴파일 상태를 한 번 더 확인하는 것이 좋다.
라이선스는 MIT이며, 자세한 내용은 루트 LICENSE에 포함되어 있다.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Unity Resource RAG

한눈에 보기

주요 구성 요소

Unity 쪽

Sidecar 쪽

저장소 구조

요구 사항

설치

1) Python 설정

2) Unity 설정

3) MCP 클라이언트 설정

빠른 시작

기본 흐름

CLI 예시

MCP preset 예시

문서 바로가기

핵심 문서

참고 자료

링크

참고 사항

About

Uh oh!

Releases 6

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
Packages/com.hanjo92.unity-resource-rag		Packages/com.hanjo92.unity-resource-rag
docs		docs
examples		examples
pipeline		pipeline
specs		specs
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Unity Resource RAG

한눈에 보기

주요 구성 요소

Unity 쪽

Sidecar 쪽

저장소 구조

요구 사항

설치

1) Python 설정

2) Unity 설정

3) MCP 클라이언트 설정

빠른 시작

기본 흐름

CLI 예시

MCP preset 예시

문서 바로가기

핵심 문서

참고 자료

링크

참고 사항

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages