HanokBuilder

한국 전통 건축 공간을 3D로 직접 조립하고 편집하는 인터랙티브 제작 도구입니다. 전문 3D 소프트웨어 지식 없이도 국가 문화공공데이터 기반 에셋을 배치하고 AI 추천으로 장면을 구성하며 PNG로 저장할 수 있습니다.

📦

에셋 라이브러리

완성형 한옥부터 개별 부품, 소품, 디지털 휴먼까지 문화공공데이터 기반 에셋

✨

AI 에셋 추천

자연어 입력 한 줄로 Claude Haiku가 최대 30개 관련 에셋 즉시 추천

🌅

4가지 배경 프리셋

맑은날 · 저녁노을 · 밤 · 자연 — 원클릭 전환으로 분위기 즉시 변경

🛠

실시간 3D 편집

이동 · 회전 · 크기 핸들 조작과 수치 입력으로 정밀하게 배치 편집

↩

20단계 되돌리기

CtrlZ로 최대 20단계까지 작업 이력 복원

📸

PNG 캡처

UI 패널 제외, 뷰포트 화면만 바탕화면에 날짜·시간 파일명으로 저장

🗺

AI 자동 레이아웃

테마 한 줄로 Claude가 건물·자연물을 단계적으로 배치해 완성형 씬을 자동 설계

💬

자연어 씬 편집

"사랑채를 동쪽으로 5m 이동해줘" — 대화 맥락을 기억하며 씬을 직접 수정

🏛

문화재 해설

건물 클릭 시 Claude가 역사·건축·문화 맥락을 담은 3문장 해설을 즉시 생성

엔진 / 렌더러: Unity 6 (6000.3.16f1) · Universal Render Pipeline (URP)
AI 기능: Claude Haiku API — 에셋 추천 · AI 자동 레이아웃 · 자연어 씬 편집 · 문화재 해설 4가지 모드
에셋 원천: 문화포털 메타버스데이터랩 공개 3D 데이터 (한옥 건축·소품·디지털 휴먼)
주요 활용 대상: 게임 개발자·인디 팀, 교육자·학생, 웹툰 작가, 메타버스 기획자, 박물관·문화기관

Preview

시뮬레이션 영상

HanokBuilder의 주요 기능과 작업 흐름을 영상으로 확인할 수 있습니다.

Interface

화면 구성

실행 화면은 7개 영역으로 나뉩니다. 번호를 기준으로 각 영역의 역할을 확인하세요.

에셋 라이브러리
카테고리와 검색으로 에셋 탐색. 썸네일 클릭 시 즉시 배치.
검색 · 카테고리 필터
한글 키워드로 이름·태그 즉시 필터링. 완성형/부품형 탭 전환.
배경 프리셋 패널
맑은날 · 저녁노을 · 밤 · 자연 4가지 하늘·분위기 전환.
3D 뷰포트
에셋을 배치하고 카메라를 조작하는 주 편집 공간.
편집 도구 툴바
이동·회전·크기·삭제 도구 + 캡처·초기화. 드래그로 위치 이동 가능.
부재 정보 패널
선택 에셋 이름·위치·회전·크기 수치 확인 및 조정.
AI 프롬프트 바
[맵]·[씬] 모드 토글 및 자연어 입력. 에셋 추천·자동 레이아웃·자연어 씬 편집 기능 전환.

Quick Start

처음 시작하는 5단계

실행하면 맑은날 배경이 자동 설정됩니다. 아래 순서대로 따라가 보세요.

배경 선택
상단 배경 프리셋 패널에서 원하는 공간을 고릅니다. 배경이 바뀌어도 배치한 에셋은 유지됩니다.
에셋 탐색 및 배치
좌측 라이브러리에서 카테고리를 탐색하거나 검색창에 키워드를 입력합니다. 썸네일 클릭 시 뷰포트 중앙에 즉시 배치됩니다.
AI로 에셋 발견 · 씬 구성
하단 프롬프트 바에 원하는 장면을 입력합니다. 예: "나무로 둘러싸인 집". 결과를 클릭하면 즉시 배치됩니다. 맵 버튼으로 테마 기반 자동 설계, 씬 버튼으로 자연어 직접 편집도 가능합니다.
배치 편집
툴바에서 이동 1 · 회전 2 · 크기 3 도구로 정밀 조정합니다. 실수하면 CtrlZ로 최대 20단계 되돌릴 수 있습니다.
결과 저장
P키 또는 툴바 캡처 버튼을 누릅니다. 뷰포트 화면이 Hanok_yyyyMMdd_HHmmss.png로 바탕화면에 저장됩니다.

API 키가 필요한 기능

AI 추천은 Claude API 키 설정이 필요합니다. 키가 없으면 키워드 기반 로컬 추천으로 자동 대체됩니다.

Backgrounds

배경 프리셋

화면 상단 중앙 패널에서 전환합니다. 배경은 교체되지만 사용자가 배치한 에셋은 그대로 유지됩니다.

☀️

맑은날 기본

청명한 낮 하늘 아래 햇살이 내리쬐는 화창한 환경

일반 배치 작업, 에셋 색감·디테일 확인

🌇

저녁노을

붉은 노을이 하늘을 물들이는 따뜻한 황혼 분위기

드라마틱한 구도 캡처, 감성적 씬 연출

🌙

밤

별이 빛나는 어두운 밤하늘과 고요한 야간 분위기

야간 씬 레퍼런스, 조명 효과 강조 장면

🌿

자연

녹음이 우거진 자연 속 한옥 풍경의 싱그러운 환경

자연물·수목 배치, 정원·경관 구성

Asset Library

에셋 라이브러리

카테고리 구조

완성형	봉수당, 사랑채 등 한옥 건물 전체 모델
부품형	보 · 단청 · 장식 · 문 · 바닥 · 난간 · 마루 · 자연물 · 지붕 · 벽 · 목재 등

사용 방법

검색창에 한글 키워드를 입력하면 이름·태그 기준으로 즉시 필터링됩니다.
카테고리 탭을 선택하면 해당 분류만 표시됩니다.
썸네일을 클릭하면 3D 뷰포트 중앙에 즉시 배치됩니다.
썸네일은 실제 3D 모델을 촬영해 순차 생성합니다. 처음 실행 시 잠시 기다리세요.

Camera Controls

카메라 조작

Unity Editor Scene View와 동일한 방식입니다. 선택한 에셋을 기준점으로 카메라가 공전하는 오비트 구조입니다.

마우스

시점 회전	우클릭 드래그 · `Alt` + 좌클릭 드래그
화면 이동	중간버튼 드래그 · `Shift` + 우클릭 드래그
확대/축소	스크롤 휠 (커서 방향으로 이동)
정밀 줌	`Ctrl` + 스크롤

키보드 이동 (우클릭 유지 중)

앞뒤	`W` / `S`
좌우	`A` / `D`
위아래	`E` / `Q`
빠른 이동	`Shift` + 이동키 (3배속)

고정 시점 (Numpad)

`Numpad 1`	정면 뷰 (직교) — 높이 정렬 확인
`Numpad 3`	우측면 뷰 (직교) — 깊이 정렬 확인
`Numpad 7`	탑뷰 (직교) — 평면 배치·대칭 확인
`Numpad 9`	후면 뷰 (직교)
`Numpad 5` / `0`	원근 뷰 (기본)

포커스

`F`	선택 에셋을 화면 중앙에 맞추어 카메라 자동 이동
`Z`	배치된 모든 에셋이 화면에 들어오도록 카메라 조정

시점 전환 Ease-out

시점 전환과 포커스 이동은 목표에 가까워질수록 자연스럽게 감속합니다. 급격한 화면 전환 없이 공간 감각을 유지합니다.

Editing Tools

편집 도구

좌측 플로팅 툴바에서 선택하거나 숫자 단축키로 전환합니다. 툴바는 드래그로 화면 어디로든 이동 가능합니다.

도구	단축키	동작
이동	`1`	에셋 드래그 시 마우스 방향으로 레이캐스트 발사. 다른 에셋 표면 위에 올릴 수 있고, 표면 없으면 Y=0 평면에 자동 스냅.
회전	`2`	X(빨강)·Y(초록)·Z(파랑) 3색 원형 링 핸들 드래그. 카메라 시점에 따른 감도 자동 보정.
크기	`3`	축 방향 큐브 핸들(단축 변경) / 중앙 구형 핸들(균일) / `Ctrl`+스크롤 / 에셋 상단 플로팅 핸들 드래그.
삭제	`4`	에셋 클릭 즉시 삭제.
회전 초기화	`H`	선택 에셋의 회전값을 0으로 복원.
캡처	`P`	현재 뷰포트를 PNG로 바탕화면에 저장. UI 패널 제외.

회전 도구 — 저녁노을 배경에서 Y축 270도 회전 — 회전(2) 도구 — 우측 패널에서 X·Y·Z 값을 직접 입력하거나 드래그로 회전합니다.

크기 조정 — AI 맵 모드에서 자동 scale 적용 결과 — 크기(3) 도구 또는 우측 패널 배율 버튼(0.5× · 1× · 2× · 3×)으로 에셋 크기를 조정합니다.

추가 단축키

`CtrlD`	선택 에셋 복제 — 원본에서 오른쪽 2m 위치에 생성
`CtrlZ`	되돌리기 — 최대 20단계
`Esc`	선택 해제

에셋 배치 자동 보정

크기 정규화 — FBX 단위 차이로 크기가 지나치게 크면 자동으로 표준 크기로 정규화합니다.
바닥 정렬 — 에셋 바닥면이 항상 Y=0 평면에 정확히 닿도록 자동 조정됩니다.
선택 링 — 에셋 선택 시 바닥 둘레에 남색 원형 링이 나타나 위치와 범위를 표시합니다.

Asset Info Panel

부재 정보 패널

에셋 조작 패널 — 위치·회전·크기 수치 조정 — 우측 패널에서 이름과 변형값을 확인·조정합니다.

에셋을 클릭하면 해당 부재의 한글 표시명과 변형 조정 영역이 표시됩니다. 선택 전에는 "부재를 선택하세요" 안내가 나타납니다.

위치	X·Y·Z 입력 칸 직접 입력 또는 `-`/`+` 버튼. 간격 선택: `0.05 / 0.1 / 0.5 / 1`m
회전	각도 직접 입력 또는 `-90°`/`+90°` 버튼. 간격: `1 / 5 / 15 / 45`도. `초기화`로 전체 0 복원.
크기	단일 입력으로 균일 조정. `0.5×` `1×` `2×` `3×` 배율 버튼 즉시 적용.
빠른 작업	패널 하단 복제 · 삭제 · 선택 해제 버튼 (도구 전환 불필요)

입력 필드 간 이동: Tab 키

AI Features

AI 기능

화면 하단 중앙 프롬프트 바에서 3가지 AI 모드를 선택해 씬을 구성할 수 있습니다. 모두 Claude Haiku 모델을 사용하며, API 키 설정이 필요합니다.

API 키 설정

첫 실행 시 API 키 입력 모달이 자동으로 나타납니다. 이후에는 프롬프트 바 우측 ⚙ 버튼으로 언제든 변경할 수 있습니다. console.anthropic.com에서 발급한 키(sk-ant-…)를 붙여넣으세요. 키는 기기 내부에만 저장됩니다. 키 없이도 키워드 기반 로컬 추천이 자동 작동합니다.

프롬프트 바 구조

`맵`	AI 자동 레이아웃 모드 — 테마 입력 시 Claude가 건물·자연물을 단계적으로 배치
`씬`	자연어 씬 편집 모드 — 자연어 명령으로 배치된 오브젝트를 이동·회전·배치·삭제
기본 (토글 없음)	AI 에셋 추천 — 관련 에셋 최대 30개 추천, 클릭 시 즉시 배치
`⚙`	API 키 설정 패널 열기

AI 에셋 추천 (기본 모드)

모드 토글 없이 자연어를 입력하면 Claude가 에셋 카탈로그에서 최대 30개를 추천합니다. 결과는 프롬프트 바 위 가로 스크롤 목록으로 표시되며, 클릭 시 즉시 배치됩니다.

AI 추천 결과 — 가로 스크롤 에셋 목록과 프롬프트 바 — 추천 에셋이 프롬프트 바 위 가로 스크롤 목록으로 표시됩니다. 클릭하면 즉시 배치됩니다.

입력 예시	추천 결과
"나무로 둘러싸인 집"	수목·정자·담장 관련 에셋
"조선 장터 상인과 바구니, 깃발"	행상인·전통 수레·깃발 에셋
"아치형 대문 주변 풍경"	문·기와·돌담 관련 에셋

AI는 에셋을 자동 배치하지 않습니다

추천 목록에서 직접 클릭해야 배치됩니다. 탐색 진입장벽을 낮추는 보조 기능입니다. API 키 미설정 시 키워드 기반 로컬 추천이 자동으로 작동합니다.

[맵] AI 자동 레이아웃

맵 버튼을 활성화한 뒤 테마를 입력하면 Claude가 최대 20턴에 걸쳐 건물과 자연물을 단계적으로 배치해 완성형 씬을 설계합니다. 배치 후 겹침이 감지되면 자동으로 다른 좌표를 선택합니다.

입력 예시	설계 결과
"소규모 양반가 안채 배치"	건물 2~4개 + 자연물 6~10개
"사찰 중심 — 주불전, 종루, 소나무"	사찰 구조 + 소나무군
"밀도 높은 조선 시장 번화가"	건물 10~14개 + 자연물 12~18개
"대규모 궁궐 배치"	건물 13~18개 + 자연물 15~25개

밀도 기준	조용한/소규모 → 건물 2~4개 · 일반 마을 → 5~7개 · 밀도 높음 → 10~14개 · 대규모/궁궐 → 13~18개
설계 완료 표시	AI 추천 결과 패널 헤더에 "완성! [설계 해설]" 문구로 표시됩니다.
진행 중 표시	패널 헤더에 "AI가 설계 중…" / "수정 중…" 상태가 순서대로 표시됩니다.
모드 종료	`맵` 버튼 재클릭으로 비활성화합니다.

한국 전통 건축 테마 키워드

양반가·사찰·관아·서원·시장·정원·마을 키워드를 사용하면 테마의 건축적·문화적 규칙에 따라 배치합니다. 설계 완료 후 개별 에셋을 수동으로 추가·이동하거나 씬 모드로 자연어 편집하여 세부 조정이 가능합니다.

[씬] 자연어 씬 편집

씬 버튼을 활성화하면 중앙 하단에 채팅 인터페이스가 열립니다. 씬에 배치된 오브젝트를 자연어로 직접 수정할 수 있으며, 이전 대화를 기억해 "그거", "방금 배치한 것" 같은 문맥 표현도 인식합니다.

자연어 씬 편집 모드 — 채팅 인터페이스와 오브젝트 조작 결과 — 씬 모드 채팅 패널에서 자연어로 오브젝트를 이동·회전·배치·삭제합니다.

명령 예시	동작
"사랑채를 동쪽으로 5m 옮겨줘"	해당 건물 X축 +5m 이동
"처마를 45도 회전해줘"	선택 오브젝트 Y축 45도 회전
"정자 삭제해줘"	정자 오브젝트 씬에서 제거
"연못 하나 추가해줘"	연못 에셋을 카메라 중심에 배치
"그걸 더 북쪽으로 이동해줘"	직전 대상 오브젝트 Z축 이동

방향 기준	동쪽 = +X · 서쪽 = −X · 남쪽 = −Z · 북쪽 = +Z
대화 히스토리	세션 동안 대화 맥락 유지. "그거", "방금 것" 같은 지시어 인식 가능.
결과 확인	명령 실행 후 채팅 패널에 작업 요약이 말풍선으로 표시됩니다.
모드 종료	`씬` 버튼 재클릭으로 채팅 패널이 닫힙니다.

맵 + 씬 모드 조합 활용

맵 모드로 전체 구조를 잡은 뒤 씬 모드로 세부 위치를 조정하는 흐름이 가장 효율적입니다. 씬 편집 중에도 에셋 라이브러리에서 직접 추가 배치가 가능합니다.

Cultural Guide

문화재 해설 패널

뷰포트에서 건물이나 에셋을 클릭하면 Claude가 해당 건축물의 역사적 배경·건축 특징·문화적 의미를 담은 3문장 해설을 자동으로 생성해 말풍선 형태로 표시합니다.

문화재 해설 말풍선 — 건물 위 3문장 해설 표시 — 건물 클릭 시 Claude가 역사·건축·문화 맥락을 담은 3문장 해설을 말풍선으로 표시합니다.

패널 상태

상태	표시 형태	전환 방법
Expanded	건물 위 말풍선 — 제목(금색)·해설 본문 3문장 전체 표시	에셋 클릭 시 기본 상태 / Collapsed pill 클릭
Collapsed	건물 위 작은 pill — "▸ 건물명"만 표시	말풍선 [−] 접기 버튼 클릭
Hidden	표시 없음	말풍선 [✕] 닫기 클릭 (같은 에셋 재클릭 시에도 Hidden 유지)

사용 방법

에셋 클릭
뷰포트에서 건물이나 에셋을 클릭합니다. Claude API 호출이 즉시 시작됩니다.
해설 확인
잠시 후 건물 위에 말풍선이 나타납니다. 역사·건축·문화 맥락을 담은 3문장이 표시됩니다.
패널 관리
[−]으로 pill 상태로 줄이거나 [✕]로 닫습니다. 다른 에셋을 클릭하면 새 해설이 생성됩니다.

해설은 에셋마다 실시간으로 생성됩니다

Claude Haiku 모델이 건물 이름과 카테고리를 기반으로 문화재 큐레이터 관점의 해설을 생성합니다. API 키가 설정되어 있어야 작동합니다. 마크다운 없는 완결된 문단 형식으로 표시됩니다.

Capture

화면 저장

툴바 캡처 버튼 또는 P키로 현재 뷰포트를 이미지로 저장합니다.

편집 도구 툴바 — 캡처(P) 버튼 위치 — 툴바 하단 캡처(`P`) 버튼입니다.

저장 위치	사용자 바탕화면
파일명 형식	`Hanok_yyyyMMdd_HHmmss.png`
포맷	PNG (무손실)
캡처 범위	3D 뷰포트만 저장. 좌측·우측 UI 패널 및 툴바는 제외됩니다.

좋은 캡처를 위한 흐름

배경 선택 → 에셋 배치 완료 → Numpad 1/3/7로 구도 확인 → F로 주요 에셋 초점 → P로 캡처.

Keyboard Shortcuts

단축키 전체 목록

단축키	기능
`1`	이동 도구 — 에셋 드래그 배치
`2`	회전 도구 — 3축 링 핸들 드래그
`3`	크기 도구 — 핸들 드래그 / `Ctrl`+스크롤
`4`	삭제 도구 — 클릭 즉시 삭제
`H`	선택 에셋 회전값 초기화
`P`	뷰포트 캡처 → 바탕화면 PNG 저장
`CtrlD`	선택 에셋 복제 (오른쪽 2m)
`CtrlZ`	되돌리기 (최대 20단계)
`Esc`	선택 해제

단축키	기능
우클릭 드래그	시점 회전 (오비트)
중간버튼 드래그	화면 이동 (패닝)
스크롤 휠	확대/축소
`Ctrl` + 스크롤	정밀 줌
`W` / `S`	앞뒤 이동 (우클릭 유지)
`A` / `D`	좌우 이동 (우클릭 유지)
`E` / `Q`	위아래 이동 (우클릭 유지)
`Shift` + 이동키	3배속 이동
`F`	선택 에셋 화면 중앙 포커스
`Z`	배치된 전체 에셋 프레임 보기

단축키	기능
`Numpad 1`	정면 뷰 (직교) — 높이 정렬
`Numpad 3`	우측면 뷰 (직교) — 깊이 정렬
`Numpad 7`	탑뷰 (직교) — 평면 배치 확인
`Numpad 9`	후면 뷰 (직교)
`Numpad 5` / `0`	원근 뷰 (기본)

활용 예시

기둥 간격 확인 → Numpad 7 탑뷰 · 지붕 높이 맞추기 → Numpad 1 정면뷰 · 처마 깊이 조정 → Numpad 3 우측뷰

Troubleshooting

문제 해결

에셋 라이브러리에 썸네일이 보이지 않습니다

썸네일은 실제 3D 모델을 전용 카메라로 순차 촬영해 생성합니다. 처음 실행 시 잠시 기다리세요. 에셋이 많을수록 시간이 더 걸립니다. 한 번에 하나씩 순차 생성해 화면 멈춤(프레임 스파이크)을 방지합니다.

썸네일을 클릭해도 에셋이 배치되지 않습니다

에셋 리소스가 Assets/HanokBuilder/Resources/HanokAssets/ 경로에 있는지 확인하세요. FBX 파일은 Prefab으로 변환 후 해당 경로에 넣어야 자동 로드됩니다.

AI 추천 기능이 작동하지 않습니다

Claude API 키 설정 여부를 먼저 확인하세요. 키가 없으면 키워드 기반 로컬 추천으로 자동 대체됩니다. 입력 문장을 더 구체적으로 작성해보세요. 예: "상인" → "조선 장터 상인 남자 캐릭터"

[맵] AI 자동 레이아웃이 응답하지 않거나 너무 오래 걸립니다

맵 모드는 최대 20턴의 반복 API 호출로 씬을 설계하므로 규모에 따라 수십 초가 소요될 수 있습니다. "AI가 설계 중…" 표시가 나타나면 정상 진행 중입니다. 응답이 없다면 API 키를 확인하고, 네트워크 연결 상태를 점검하세요. 입력을 더 구체적으로 작성하거나 규모를 줄이는 것도 도움이 됩니다. 예: "대규모 궁궐" → "소규모 양반가"

[씬] 자연어 편집 명령이 올바르게 실행되지 않습니다

씬에 오브젝트가 하나 이상 배치되어 있어야 합니다. 명령에 오브젝트 이름을 명확히 포함하세요. 예: "오브젝트 이동" → "사랑채를 동쪽으로 3m 이동해줘". 방향은 동(+X)·서(−X)·남(−Z)·북(+Z) 기준입니다. 에셋 추가 시 카탈로그에 없는 이름이면 배치되지 않습니다. 채팅 패널의 AI 응답 메시지에서 구체적인 오류 원인을 확인할 수 있습니다.

에셋이 화면에 보이지 않거나 엉뚱한 위치에 있습니다

Z키로 전체 보기를 시도합니다. 에셋이 카메라 범위 밖에 있을 수 있습니다. 우측 패널에서 위치를 X=0, Y=0, Z=0으로 직접 입력하거나, 라이브러리에서 해당 에셋을 다시 클릭해 재배치하세요.

회전 핸들 링이 지나치게 크거나 작습니다

FBX 파일이 cm 단위로 모델링된 경우 bounds가 100배 크게 인식될 수 있습니다. 기즈모가 카메라 거리 기반으로 자동 전환합니다. 근본 해결은 Unity FBX 임포트 설정에서 Scale Factor = 0.01로 설정하는 것입니다.

한글이 깨져 보이거나 폰트가 이상합니다

NotoSansKR SDF 폰트와 TextMesh Pro 리소스가 정상 import되어 있는지 확인하세요. Unity 6에서 TextAlignmentOptions.MidlineCenter는 제거되었으므로 TextAlignmentOptions.Center를 사용해야 합니다.

에셋을 클릭해도 선택되지 않습니다

FBX 계층 구조에서 Collider가 자식 오브젝트에만 있을 때 발생합니다. 루트 및 모든 자식 Collider에 SelectableAsset 컴포넌트가 부착되어야 합니다. AttachSelectable() 함수를 통해 자동으로 처리됩니다.

이동·회전이 의도와 다르게 작동합니다

우측 부재 정보 패널의 수치 입력을 먼저 사용해보세요. 드래그보다 정확합니다. 회전은 -90°/+90° 버튼으로 90도 단위를 먼저 잡고 세밀하게 조정하는 것을 권장합니다.

Culture Data

문화데이터 출처

HanokBuilder의 에셋 라이브러리는 국가기관이 공개한 문화공공데이터를 원천으로 합니다.

활용 데이터	제공기관	플랫폼
건축물 완성형 3D 데이터	한국문화정보원	문화포털 메타버스데이터랩
건축물 부품형 3D 데이터	한국문화정보원	문화포털 메타버스데이터랩
디지털 휴먼 데이터	한국문화정보원	문화포털 메타버스데이터랩
공간소품 3D 오브젝트	한국문화정보원	문화포털 메타버스데이터랩

데이터 처리 방식

수집한 데이터는 에셋 식별자(assetKey), 한글 표시명, 카테고리, 검색 태그로 재구조화해 라이브러리 검색과 AI 추천에서 동일하게 활용합니다. 원본 FBX·텍스처 파일은 Git LFS 용량 제한을 고려해 코드와 분리 관리합니다.