unity-json-tree-viewer

JSON 텍스트나 .json 파일을 트리로 시각화하고, 검색·복사·인라인 편집·저장까지 한 창에서 처리하는 Unity 에디터 윈도우입니다. UIToolkit(TreeView, TwoPaneSplitView)으로 구현되었고, Newtonsoft.Json 으로 파싱합니다.

English

파일을 열면 타입 배지가 붙은 트리로 펼쳐집니다. 위는 원문 입력란, 아래는 검색창과 트리입니다.

주요 기능

• 입력: 붙여넣기, 클립보드 로드, 로컬 .json 파일 로드. 입력 후 300ms 디바운스로 자동 파싱됩니다.
• 트리 표시: 노드마다 타입 배지(obj / arr / int / num / str / bool / null)와 값 미리보기가 붙습니다. 객체는 필드 수, 배열은 항목 수를 요약으로 보여줍니다.
• 검색: 공백으로 나눈 토큰을 AND 매칭합니다. Key=값 페어 매칭, t:key / t:value / t:path 타깃 한정, Regex / Exact 토글, 키 이름 자동완성을 지원합니다. 매칭된 노드와 그 조상만 남기고 나머지는 잘라냅니다.
• 선택 유지: 검색 필터를 바꾸거나 지워도 사용자가 선택했던 노드는 유지되고, 검색을 지우면 첫 선택 항목으로 스크롤합니다.
• 복사: 트리 항목 우클릭으로 서브트리 JSON(Indented / Compact), 경로, 키, 값을 클립보드에 복사합니다.
• 인라인 편집·저장: 로컬 파일을 열었거나 호출자가 onSave 콜백을 넘긴 경우, 잎 노드를 더블클릭해 값을 고치고 저장할 수 있습니다. 타입은 보존되며 변환에 실패하면 원본을 유지합니다.
• Project 윈도우 연동: .json 에셋 더블클릭을 가로채 이 뷰어로 열고, TextAsset 인스펙터에 켜기/끄기 토글과 "지금 열기" 버튼을 추가합니다.
• 튜토리얼: 첫 실행 시 6단계 코치마크 오버레이가 자동으로 표시됩니다. 상단 툴바의 "튜토리얼" 버튼으로 다시 볼 수 있습니다.
• 외부 도구 연동 API: 다른 에디터 도구가 메모리상의 JSON 문자열을 넘겨 뷰어를 띄우고, 저장 결과를 콜백으로 받을 수 있습니다.

요구 사항

항목	내용
Unity	Unity 6 (6000.3.22f1) 에서 빌드와 동작을 확인했습니다. TreeView.selectionChanged 등 2023.2 에 도입된 UIToolkit API 를 쓰므로 package.json 의 최소 버전은 2023.2 로 선언했습니다. 그 사이 버전은 검증하지 않았습니다.
의존 패키지	com.unity.nuget.newtonsoft-json 3.2.1 이상. package.json 의 dependencies 에 선언되어 있어 Package Manager 로 설치하면 함께 해결됩니다.
UI 언어	버튼·상태 메시지·툴팁·튜토리얼 문구는 한국어입니다.

설치

Package Manager (git URL)

Window > Package Manager > + > Add package from git URL... 에 저장소 URL 을 입력합니다.

https://github.com/ez8801/unity-json-tree-viewer.git

또는 Packages/manifest.json 의 dependencies 에 직접 추가합니다.

{
  "dependencies": {
    "com.minubaek.json-tree-viewer": "https://github.com/ez8801/unity-json-tree-viewer.git"
  }
}

특정 버전에 고정하려면 URL 뒤에 #v1.0.0 처럼 태그를 붙입니다.

로컬 경로 / Assets 복사

• 저장소를 클론한 뒤 Add package from disk... 로 package.json 을 선택해도 됩니다.
• UPM 을 쓰지 않으려면 Editor/ 폴더를 프로젝트의 Assets/ 아래 아무 곳에 복사합니다. .asmdef 가 함께 들어가므로 별도 어셈블리(JsonTreeViewer.Editor)로 컴파일되며, Newtonsoft.Json 이 프로젝트에 이미 있어야 합니다.

.meta 파일이 저장소에 포함되어 있습니다. git URL 로 설치되는 패키지는 읽기 전용이라 Unity 가 .meta 를 생성하지 않고, 없는 파일은 무시하기 때문입니다.

사용법

열기

방법	설명
메뉴	Window > JSON Tree Viewer
Project 윈도우	.json 에셋을 더블클릭하면 뷰어로 열립니다. 인스펙터 토글이 꺼져 있으면 Unity 기본 동작(외부 에디터 등)으로 넘어갑니다.
인스펙터	.json TextAsset 을 선택하면 인스펙터 상단에 "더블클릭 시 JSON Tree Viewer 로 열기" 토글과 "지금 JSON Tree Viewer 로 열기" 버튼이 나타납니다.

입력 영역

상단 카드가 JSON 입력란입니다. 위아래 경계를 드래그하면 입력란 높이를 조절할 수 있습니다.

버튼	동작
파일	파일 선택 대화상자로 .json / .txt 를 불러옵니다. 편집·저장이 활성화됩니다.
붙여넣기	클립보드 내용을 입력란에 넣고 파싱합니다.
Parse	디바운스를 기다리지 않고 즉시 파싱합니다.
저장	현재 트리를 원본 파일(또는 onSave 콜백)에 반영합니다. 파일을 열지 않았으면 비활성입니다.
초기화	입력·트리·검색·선택을 모두 비웁니다.

입력란을 직접 수정하면 파일·콜백 연결이 해제되고 편집·저장이 비활성으로 바뀝니다. 파싱 결과와 최근 동작은 하단 상태바에 표시됩니다.

검색 문법

입력	의미
foo bar	두 토큰을 모두 포함하는 노드만 남깁니다 (AND). 기본은 대소문자 무시 부분 일치입니다.
Key=900159 또는 Key:900159	같은 노드에서 키가 Key 에 매치하고 값이 900159 에 매치해야 합니다.
t:key foo	키 이름에서만 찾습니다. t:k 도 됩니다.
t:value 100	잎 노드 값에서만 찾습니다. t:v 도 됩니다.
t:path items[0]	노드 경로($.items[0].name 형식)에서만 찾습니다. t:p 도 됩니다.
Regex 토글	각 토큰을 정규식으로 해석합니다. 컴파일에 실패하면 상태바에 경고가 뜹니다.
Exact 토글	부분 일치 대신 완전 일치로 비교합니다.

• 토큰 양끝의 : " ' , ; = ( ) { } [ ] 는 제거되므로 JSON 원문에서 "event_key": 60010618 를 그대로 붙여 넣어도 동작합니다.
• 검색창 아래 이탤릭 라벨에 파싱된 타깃과 토큰이 실시간으로 표시됩니다.
• 마지막 토큰을 입력하는 동안 트리 안의 키 이름 후보가 자동완성 팝업으로 뜹니다. ↑ / ↓ 로 고르고 Enter 또는 Tab 으로 확정, Esc 로 닫습니다. Key=tut 처럼 페어의 우변을 입력 중이면 우변만 교체됩니다.

화면 예시

id=900159 는 키가 id 이고 값이 900159 인 노드만 남깁니다. 두 플레이어가 같은 아이템을 가진 위치가 한눈에 드러납니다.

같은 쿼리라도 Exact 토글에 따라 결과가 달라집니다. 부분 일치는 playerId 와 guildRaid 까지 잡지만, 완전 일치는 키가 정확히 id 인 노드만 남깁니다.

t:key id — 부분 일치로 15건.

t:key id + Exact — 완전 일치로 11건.

입력하는 동안 트리 안의 키 이름이 자동완성으로 뜹니다.

값 한정과 정규식 예시

t:value legendary — 잎 노드 값에서만 찾습니다.

900\d+ + Regex — 토큰을 정규식으로 해석합니다. 토큰 양끝의 구두점은 제거되므로 } ) ] 로 끝나는 패턴은 피합니다.

우클릭 메뉴

항목	복사되는 내용
서브트리 복사 (JSON, Indented)	해당 노드 이하를 들여쓴 JSON 으로
서브트리 복사 (JSON, Compact)	해당 노드 이하를 한 줄 JSON 으로
경로 복사	$.a.b[2].c 형식 경로
키 복사	노드 이름 (배열 원소는 [i])
값 복사	잎 노드면 따옴표를 뗀 원본 값, 컨테이너면 들여쓴 JSON

인라인 편집과 저장

1. "파일" 버튼으로 로컬 JSON 을 열거나, 외부 도구가 onSave 콜백을 넘겨 뷰어를 띄웁니다.
2. 잎 노드를 더블클릭하면 값 칸이 입력 필드로 바뀝니다. Enter 로 확정, Esc 로 취소합니다.
3. 타입은 보존됩니다. 정수 노드에 abc 를 넣으면 변환에 실패해 원본이 유지되고 상태바에 이유가 표시됩니다. null 노드는 편집 대상이 아닙니다.
4. 변경이 있으면 윈도우 제목 끝에 * 가 붙습니다.
5. "저장" 을 누르면 트리 전체를 Formatting.Indented 로 직렬화해 원본 파일에 덮어씁니다. 로드 이후 파일이 외부에서 바뀌었으면 덮어쓸지 묻습니다.

튜토리얼

첫 실행 시 입력 / 검색 / 검색 옵션 / 트리 / 저장 / 상태바 순서로 6단계 코치마크가 표시됩니다. 각 단계는 8초 후 자동으로 넘어가고, 완료 또는 건너뛰기 시 EditorPrefs 에 기록되어 다시 자동 표시되지 않습니다. 상단 툴바 우측 "튜토리얼" 버튼으로 언제든 다시 볼 수 있습니다.

외부 도구 연동 API

다른 에디터 도구에서 메모리상의 JSON 을 바로 열 수 있습니다. 호출하는 어셈블리가 별도 .asmdef 를 쓰면 references 에 JsonTreeViewer.Editor 를 추가합니다. Assembly-CSharp-Editor 는 autoReferenced 설정 덕분에 추가 작업 없이 참조됩니다.

using JsonTreeViewer.Editor;

// 읽기 전용으로 열기. subtitle 은 윈도우 제목에 붙는다.
JsonTreeViewerWindow.OpenWith(json, subtitle: "LoginResponse (#1001)");

// 편집·저장 허용. 사용자가 "저장" 을 누르면 직렬화된 JSON 이 콜백으로 전달된다.
// 메모리 반영, 디스크 저장, 자기 UI 갱신은 호출자 책임이다 (뷰어는 디스크를 모른다).
JsonTreeViewerWindow.OpenWith(json, "Scenarios", onSave: newJson =>
{
    _data = JsonUtility.FromJson<MyData>(newJson);
    Repaint();
});

멤버	설명
static JsonTreeViewerWindow OpenWith(string json, string subtitle = null, Action<string> onSave = null)	윈도우를 띄우고 JSON 을 주입합니다. onSave 가 null 이면 읽기 전용입니다.
void SetJson(string json)	이미 열린 윈도우에 JSON 을 다시 주입합니다. 파일 연결은 해제됩니다.
void LoadFromPath(string path)	경로로 파일을 로드합니다. 상대 경로는 절대 경로로 정규화됩니다.

CreateGUI 가 아직 끝나지 않은 시점에 호출해도 다음 틱에 재시도하므로 안전합니다.

설정 (EditorPrefs)

키	기본값	의미
JsonTreeViewer.OpenJsonInViewer	true	.json 더블클릭을 뷰어로 가로챌지. 인스펙터 토글과 연결되어 있습니다.
JsonTreeViewerWindow.TutorialSeen.v1	false	튜토리얼을 본 적이 있는지. 튜토리얼 문구가 크게 바뀌면 키의 v1 을 올려 모든 사용자에게 다시 노출합니다.

주의 사항

• TextAsset 인스펙터를 교체합니다. TextAssetJsonInspector 가 [CustomEditor(typeof(TextAsset))] 로 등록되므로, 프로젝트에 TextAsset 커스텀 인스펙터가 이미 있으면 충돌합니다. .json 이 아닌 TextAsset 은 기본 인스펙터 동작을 그대로 호출합니다.
• .json 더블클릭을 가로챕니다. [OnOpenAsset(1)] 로 등록되어 우선순위 0 인 다른 핸들러가 먼저 처리할 기회를 줍니다. 인스펙터 토글을 꺼서 비활성화할 수 있습니다.
• 저장은 포맷을 표준화합니다. 원본의 들여쓰기·줄바꿈·키 순서 외 공백은 보존되지 않고 Indented(2칸) 로 다시 기록됩니다.
• 파싱은 Newtonsoft.Json JToken.Parse 에 위임하므로 주석이나 후행 쉼표 같은 비표준 JSON 은 Newtonsoft 의 허용 범위를 따릅니다.
• Unity 6 에서 컴파일하면 EventBase.PreventDefault() 와 AssetDatabase.GetAssetPath(int) 가 obsolete 라는 CS0618 경고가 5건 나옵니다. 동작에는 영향이 없습니다.

저장소 구조

unity-json-tree-viewer/
├── package.json                      UPM 패키지 매니페스트
├── Documentation~/
│   └── images/                       README 스크린샷 (물결표 폴더라 Unity 가 임포트하지 않음)
├── Editor/
│   ├── JsonTreeViewer.Editor.asmdef  에디터 전용 어셈블리 정의
│   ├── JsonTreeViewerWindow.cs       메인 윈도우 (UI 구성·파싱·검색·편집·저장·클립보드)
│   ├── JsonTreeViewerQueryParser.cs  검색 쿼리를 Key/Value/Path 타깃과 토큰으로 분해
│   ├── EditorSearchQueryParser.cs    `t:<target>` 접두 파싱 유틸리티 (internal)
│   ├── JsonTreeViewerSettings.cs     EditorPrefs 기반 전역 설정
│   ├── JsonTreeViewerWindowTutorial.cs 코치마크 튜토리얼 오버레이
│   └── TextAssetJsonInspector.cs     TextAsset 인스펙터 연동 (.json 한정)
├── CHANGELOG.md
├── LICENSE.md
├── README.md
└── README.en.md

각 파일 옆의 .meta 는 Unity 가 요구하는 에셋 메타데이터입니다.

라이선스

MIT