unityflow

Unity 워크플로우 자동화 도구입니다. Unity 에디터 없이 프리팹, 씬, 에셋을 편집하고, diff/merge하고, LLM과 통합할 수 있습니다.

CLI 명령어

unityflow hierarchy    # 계층 구조 표시
unityflow inspect      # GameObject/컴포넌트 상세 조회
unityflow get          # 경로 기반 데이터 조회
unityflow set          # 경로 기반 값 설정 (컴포넌트/오브젝트 추가·제거 포함)
unityflow create       # 새 프리팹/씬/에셋 파일 생성
unityflow normalize    # Unity YAML 파일 정규화
unityflow validate     # 구조적 무결성 검증
unityflow diff         # 두 파일 비교 (semantic)
unityflow merge        # 3-way 병합 (semantic)
unityflow refs         # 에셋 참조 검색 (GUID 기반)
unityflow anim         # 애니메이션 클립 편집 (.anim)
unityflow ctrl         # Animator Controller 편집 (.controller)
unityflow setup        # Git 통합 설정
unityflow git-textconv # Git diff용 정규화 출력

전체 옵션은 unityflow <command> --help로 확인하세요.

Claude Code 통합

Claude Code와 함께 사용하면 AI가 Unity 프로젝트를 더 효과적으로 이해하고 수정할 수 있습니다.

Plugin 설치

TrueCyan/claude-plugins에서 unityflow plugin을 설치하세요.

제공되는 Skills

Skill	설명
`unity-yaml-workflow`	Unity YAML 파일 편집 가이드 (프리팹, 씬, 에셋)
`unity-ui-workflow`	UI 프리팹 작업 가이드 (Canvas, RectTransform)
`unity-animation-workflow`	애니메이션 파일 작업 가이드 (.anim, .controller)
`unity-asset-refs`	에셋 참조 검색 가이드 (GUID 기반 역참조)
`unity-yaml-resolve`	Unity YAML 머지 컨플릭트 AI 해결 (Git/Perforce 다중 스트림 지원)

Unity Editor Bridge (MCP)

Unity Editor와 실시간 통신하여 스크린샷, 프리팹 프리뷰, 애니메이션 프레임 캡처 등 시각적 피드백을 제공합니다.

Unity 패키지 설치 (Package Manager → Add from git URL):

https://github.com/TrueCyan/unityflow.git?path=unity-bridge

Python MCP 서버 설치:

pip install unityflow[bridge]

Claude Code에 MCP 서버 등록:

Plugin을 설치하면 MCP 서버가 자동으로 등록됩니다. Plugin 없이 단독으로 사용하려면 직접 등록합니다:

claude mcp add unityflow-bridge -- unityflow-bridge

MCP Tools:

Tool	설명
`capture_screenshot`	Scene/Game View 스크린샷
`capture_prefab_preview`	프리팹 오프스크린 렌더링
`capture_animation_frames`	애니메이션 멀티프레임 캡처
`get_animator_state`	Animator 런타임 상태 (Play Mode)
`get_runtime_hierarchy`	동적 오브젝트 포함 런타임 hierarchy
`get_inspector`	컴포넌트 Inspector 데이터
`get_console_logs`	콘솔 로그/에러
`get_editor_state`	에디터 상태 (Play mode, 씬, 선택)

사용 예시

Claude Code에서 다음과 같이 요청할 수 있습니다:

Player.prefab에 머지 컨플릭트가 있어. 해결해줘.

MainMenu.prefab의 계층 구조를 보여줘.

Player의 Transform 위치를 (10, 0, 5)로 변경해줘.

현재 씬 스크린샷 찍어줘.

Player 프리팹 렌더링해서 보여줘.

설치

PyPI에서 설치 (권장)

pip install unityflow

# Unity Editor Bridge MCP 포함
pip install unityflow[bridge]

GitHub에서 설치

pip install git+https://github.com/TrueCyan/unityflow.git

소스에서 설치

git clone https://github.com/TrueCyan/unityflow
cd unityflow
pip install .

개발 환경 설치

git clone https://github.com/TrueCyan/unityflow
cd unityflow
pip install -e ".[all]"

요구 사항

Python 3.12 이상
의존성:
- unityparser>=4.0.0
- rapidyaml>=0.10.0,<0.12
- click>=8.0.0
- packaging>=21.0
- ufbx>=0.0.5
Bridge 의존성 (선택):
- mcp>=1.26.0,<2
Unity Editor Bridge:
- Unity 2021.3 이상

주요 기능

정규화: Unity YAML 파일을 결정적 형식으로 변환하여 불필요한 diff 제거
검증: 참조 유효성, 순환 참조, 중복 fileID 검사
비교/병합: 정규화된 diff 및 3-way 병합 지원
에셋 추적: 의존성 분석 및 역참조 검색
Git 통합: textconv, merge 드라이버, pre-commit 훅 지원

빠른 시작

파일 정규화

# 단일 파일 정규화
unityflow normalize Player.prefab
unityflow normalize MainScene.unity
unityflow normalize GameConfig.asset

# 여러 파일 정규화
unityflow normalize *.prefab *.unity *.asset

# 병렬 처리 (4 워커)
unityflow normalize Assets/**/*.prefab --parallel 4 --progress

# Git에서 변경된 파일만 정규화
unityflow normalize --changed-only

# 스테이징된 파일만 정규화
unityflow normalize --changed-only --staged-only

파일 검증

# 단일 파일 검증
unityflow validate Player.prefab
unityflow validate MainScene.unity

# 엄격 모드 (경고도 오류로 처리)
unityflow validate Player.prefab --strict

파일 비교

# 두 파일 비교
unityflow diff old.prefab new.prefab
unityflow diff Scene_v1.unity Scene_v2.unity

Git 통합 설정

Unity 프로젝트 루트에서 단일 명령어로 Git 통합을 설정할 수 있습니다:

# 기본 설정 (diff/merge 드라이버 + .gitattributes)
unityflow setup

# pre-commit 훅도 함께 설치
unityflow setup --with-hooks

# 글로벌 설정 (모든 저장소에 적용)
unityflow setup --global

이 명령어는 다음을 자동으로 수행합니다:

Git diff 드라이버 설정 (정규화된 diff 출력)
Git merge 드라이버 설정 (Unity 파일 3-way 병합)
.gitattributes 파일 생성/업데이트

수동 설정 (선택사항)

수동으로 설정하려면 .gitconfig에 추가:

[diff "unity"]
    textconv = unityflow git-textconv

[merge "unity"]
    name = Unity YAML Merge
    driver = unityflow merge %O %A %B -o %A --path %P

.gitattributes에 추가:

*.prefab diff=unity merge=unity text eol=lf
*.unity diff=unity merge=unity text eol=lf
*.asset diff=unity merge=unity text eol=lf

Python API 사용법

from unityflow import (
    UnityYAMLDocument,
    UnityPrefabNormalizer,
    analyze_dependencies,
    get_changed_files,
)

# Unity YAML 파일 로드 (.prefab, .unity, .asset)
doc = UnityYAMLDocument.load("Player.prefab")
doc = UnityYAMLDocument.load("MainScene.unity")
doc = UnityYAMLDocument.load("GameConfig.asset")

# 정규화
normalizer = UnityPrefabNormalizer()
content = normalizer.normalize_file("Player.prefab")

# 의존성 분석
from pathlib import Path
report = analyze_dependencies([Path("Player.prefab")])
for dep in report.get_binary_dependencies():
    print(f"{dep.path} [{dep.asset_type}]")

# Git 변경 파일 조회
changed = get_changed_files(staged_only=True)

Unity 파일 프로그래매틱 생성

from unityflow.parser import (
    UnityYAMLDocument,
    create_game_object,
    create_transform,
    create_rect_transform,
)

# 새 문서 생성
doc = UnityYAMLDocument()

# 고유 fileID 생성
go_id = doc.generate_unique_file_id()
transform_id = doc.generate_unique_file_id()

# GameObject 생성
go = create_game_object("MyObject", file_id=go_id, components=[transform_id])

# Transform 생성
transform = create_transform(
    game_object_id=go_id,
    file_id=transform_id,
    position={"x": 0, "y": 5, "z": 0},
)

# 문서에 추가 및 저장
doc.add_object(go)
doc.add_object(transform)
doc.save("MyObject.prefab")  # 또는 .unity, .asset

지원 파일 형식

카테고리	확장자
Core	`.prefab`, `.unity`, `.asset`
Animation	`.anim`, `.controller`, `.overrideController`, `.playable`, `.mask`, `.signal`
Rendering	`.mat`, `.renderTexture`, `.flare`, `.shadervariants`, `.spriteatlas`, `.cubemap`
Physics	`.physicMaterial`, `.physicsMaterial2D`
Terrain	`.terrainlayer`, `.brush`
Audio	`.mixer`
UI/Editor	`.guiskin`, `.fontsettings`, `.preset`, `.giparams`

개발

# 개발 환경 설치 (dev + bridge)
pip install -e ".[all]"

# 테스트 실행
pytest tests/

# 코드 포맷팅
black src/ tests/
ruff check src/ tests/

아키텍처와 API 상세 문서는 DEVELOPMENT.md를 참조하세요.

변경 이력은 GitHub Releases를 참조하세요.

라이선스

MIT License

Metadata

Release files for unityflow 0.11.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unityflow 0.11.3
File	Size	Uploaded
unityflow-0.11.3.tar.gz	249.6 kB	Jul 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for unityflow 0.11.3
File	Interpreter	ABI	Platform	Reset
unityflow-0.11.3-py3-none-any.whl 201.9 kB Jul 27, 2026	Python 3	none	any	Details

Total release size: 451.4 kB

Release files / unityflow-0.11.3.tar.gz

Download URL	unityflow-0.11.3.tar.gz
Size	249.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`d7c28e2c8cba44337e7dcc31708c64eb425fbba495cc46252d8bcb8a13451761`
BLAKE2b-256 checksum How to use checksums	`006e76a4adedb4cf76fe644283c2ac0c4705a6af2e053efe2235e37edc6f0e2e`
Upload date	Jul 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Release files / unityflow-0.11.3-py3-none-any.whl

Download URL	unityflow-0.11.3-py3-none-any.whl
Size	201.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c170bd4e255bad32aada13895709619a77668b1ed14e7d9dcd036fa69b32229f`
BLAKE2b-256 checksum How to use checksums	`57a59ecd7e6419a44e96028f67f60af28a0c256789a99a7ff3deb4b4ec7854e9`
Upload date	Jul 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.14`