unity-uitoolkit-add-tutorial

한국어 · English

Unity UIToolkit 기반 EditorWindow 또는 CustomEditor 인스펙터에 첫 실행 시 자동으로 표시되는 패시브 코치마크 튜토리얼을 추가하는 Claude Code 스킬입니다.

대상 .cs 파일 하나를 지정하면 다음을 자동으로 수행합니다.

• 같은 폴더에 {ClassName}Tutorial.cs 오버레이 클래스를 생성
• 대상 클래스에 RestartTutorial(), BuildTutorialSteps() 메서드를 주입
• 상단 Toolbar(EditorWindow) 또는 인스펙터 헤더 행(CustomEditor) 우측에 "튜토리얼" 버튼을 배치
• 진입점 끝에 ShowIfNeeded(...) 호출을 삽입해 첫 실행 시 한 번만 자동 표시
• UI 요소를 분석해 4~7개의 단계 초안을 생성 (문구는 검토용 초안)

결과물 미리보기

SVN 보조 창에 추가한 튜토리얼의 3번째 단계입니다. 리비전 필드를 강조하고 그 의미를 툴팁으로 설명합니다.

생성되는 튜토리얼은 다음처럼 동작합니다.

• 반투명 검은 오버레이가 창 전체를 덮어 입력을 차단합니다 (패시브).
• 현재 단계의 대상 요소를 노란 테두리로 강조하고, 그 옆에 툴팁을 배치합니다.
• 툴팁에는 Step n / N, 제목, 설명, 자동 진행 타이머, 건너뛰기 / 이전 / 다음 버튼이 있습니다.
• 각 단계는 8초 후 자동으로 다음 단계로 넘어갑니다.
• 완료 또는 건너뛰기 시 EditorPrefs 에 기록되어 다시 자동 표시되지 않습니다. "튜토리얼" 버튼으로는 언제든 재실행할 수 있습니다.

요구 사항

항목	내용
Claude Code	스킬(SKILL.md)을 지원하는 버전
Unity	UIToolkit 에디터 API(UnityEditor.UIElements)를 지원하는 버전. Unity 6 (6000.3) 에서 사용 중이며, 2021.3 LTS 이상이면 동작할 것으로 예상하나 그 외 버전은 검증하지 않았습니다
대상 도구	CreateGUI() / CreateInspectorGUI() 로 UIToolkit 트리를 구성하는 도구. IMGUI 전용(OnGUI / OnInspectorGUI 만 있는 경우)은 대상이 아닙니다

설치

Claude Code는 .claude/skills/<스킬명>/SKILL.md 를 스킬로 인식합니다. 이 저장소는 루트에 SKILL.md 가 있으므로 폴더째로 그 위치에 두면 됩니다.

프로젝트 로컬 설치

git clone https://github.com/ez8801/unity-uitoolkit-add-tutorial.git .claude/skills/unity-uitoolkit-add-tutorial

전역 설치 (모든 프로젝트에서 사용)

git clone https://github.com/ez8801/unity-uitoolkit-add-tutorial.git ~/.claude/skills/unity-uitoolkit-add-tutorial

Windows PowerShell 에서는 ~ 대신 $env:USERPROFILE 을 사용합니다.

수동 복사

SKILL.md 와 templates/ 두 항목만 있어도 동작합니다. examples/ 는 스킬이 패턴을 참고하는 용도이므로 함께 두는 것을 권장합니다.

사용법

Claude Code 세션에서 대상 파일 경로 또는 클래스명을 넘겨 호출합니다.

/unity-uitoolkit-add-tutorial Assets/Scripts/Tool/Foo/Editor/FooWindow.cs

/unity-uitoolkit-add-tutorial FooInspector

인수를 생략하면 대상을 질문합니다. 클래스명만 주면 *.cs 전체에서 EditorWindow 또는 UnityEditor.Editor 를 상속하는 동일 이름의 클래스를 찾습니다.

작업이 끝나면 생성/수정 파일, 단계 초안 표, 버전 관리에 추가할 파일 목록을 보고합니다. 단계의 Title/Description 은 초안이므로 반드시 검토해 수정하십시오.

대상 유형별 동작

대상 유형	진입점	Root 참조	튜토리얼 버튼 위치
EditorWindow	CreateGUI() 우선, 없으면 OnEnable()	rootVisualElement	상단 Toolbar 우측. 기존 Toolbar 가 있으면 spacer + 버튼을 append, 없으면 Toolbar 를 새로 만들어 최상단에 삽입
CustomEditor	CreateInspectorGUI() (없으면 신규 생성)	_root 필드로 승격·백업	인스펙터 안의 헤더 행 우측. 적절한 헤더 행이 없으면 root 최상단에 가로 행을 새로 삽입

세부 절차와 에러 처리는 SKILL.md 에 있습니다.

폴더 구조

unity-uitoolkit-add-tutorial/
├── SKILL.md                      # 스킬 본문 (Claude Code 가 읽는 절차서)
├── templates/
│   └── Tutorial.cs.template      # 오버레이 클래스 템플릿 ({{CLASS_NAME}}, {{PREFS_KEY}} 치환)
├── docs/
│   └── coachmark-overlay.png     # README 미리보기 이미지
├── examples/                     # 스킬 적용 결과 예제. "[Tutorial]" 주석이 주입된 코드다
│   ├── EditorWindow/Editor/
│   │   ├── SampleToolWindow.cs           # 기존 Toolbar 에 버튼 append 케이스
│   │   └── SampleToolWindowTutorial.cs   # 템플릿 렌더링 결과
│   └── CustomEditor/
│       ├── SampleComponent.cs            # 인스펙터 대상 컴포넌트 (Editor 폴더 밖)
│       └── Editor/
│           ├── SampleComponentInspector.cs         # 헤더 행에 버튼 append + _root 승격 케이스
│           └── SampleComponentInspectorTutorial.cs # 템플릿 렌더링 결과
├── README.md                     # 한국어
├── README.en.md                  # 영문
├── LICENSE
├── .editorconfig
├── .gitattributes
└── .gitignore

examples/ 를 Unity 프로젝트에서 직접 열어 보려면 폴더 구조 그대로 Assets/ 아래에 복사하십시오. Editor/ 폴더 규칙에 맞춰 두었으므로 별도 어셈블리 정의 없이 컴파일됩니다.

커스터마이징

생성된 {ClassName}Tutorial.cs 는 대상 프로젝트의 파일이므로 자유롭게 고칠 수 있습니다. 자주 바꾸는 항목은 다음과 같습니다.

항목	위치	설명
자동 진행 시간	AutoAdvanceMs (기본 8000)	단계당 자동 진행 대기 시간(ms)
재노출	PrefsKey 의 .v1	튜토리얼 내용이 크게 바뀌면 .v2 로 올려 모든 사용자에게 다시 노출
버튼·타이머 문구	템플릿의 "건너뛰기", "이전", "다음", "완료", "자동 진행까지 ..."	기본은 한국어. 다른 언어가 필요하면 templates/Tutorial.cs.template 를 수정한 뒤 설치
강조 색	생성자의 hl 변수	하이라이트 테두리와 툴팁 테두리 색

템플릿을 수정하면 이후 생성되는 모든 튜토리얼에 반영됩니다. 이미 생성된 파일은 영향을 받지 않습니다.

제약

• 단계 설명 문구는 초안만 생성합니다. 최종 문구는 사람이 확정해야 합니다.
• IMGUI 전용 도구는 지원하지 않습니다. 기존 OnInspectorGUI 는 IMGUIContainer 로 감싸 UIToolkit 트리에 흡수하는 방법을 제안합니다.
• 이미 {ClassName}Tutorial.cs 가 있으면 덮어쓰기 전에 확인을 요청합니다.
• .meta 파일은 생성하지 않습니다. Unity 에디터가 자동 생성한 뒤 버전 관리에 함께 추가해야 합니다.

라이선스

MIT