# Blender 지형 작업 안내

Little Cast 지형 애드온 설치, 원본 편집, JSON 내보내기와 Mac·Windows 미리보기 절차.

**상태:** 저장소 제작 계약 기준 안내 · **최종 수정:** 2026-11-01

[수족관 개선 공유 문서의 Blender 안내](https://aquarium-improvement-20261025.radiogaga-jin.chatgpt.site/#blender-guide)를 반영하고, 저장소 `Tools/Art/aquarium_terrain/README.md`와 대조했다. 아래는 제작 방법이며 이번 작업에서 Blender·앱·Windows를 실제 실행한 검증 기록이 아니다. [당시 수족관 개선 기록](/aquarium-improvement/)도 함께 볼 수 있다.

추가 안내 · 2026.10.25

## Blender에서 지형 수정하기

애드온 설치부터 JSON 내보내기와 Mac·Windows 웹 미리보기까지

main 반영 [`01d5929`](https://github.com/voidreader/LittleCast/commit/01d5929f592eb4d9db152f97edc3f9397b85748e) · 지형 원본 전환과 Windows ZIP 수정 통합

이제 지형의 기준 원본은 **테마별 .blend 파일**입니다. Blender에서 수정한 뒤 **원본 저장 + JSON 내보내기** 버튼을 누르면 앱이 사용하는 지형 자산으로 변환됩니다. 아래는 기존 생성 스크립트 편집 방식을 대체하는 현재 작업 방법입니다.

**애드온이 무엇인가요?**

프로젝트에서 만든 **Little Cast 지형 JSON 내보내기**는 Blender에 내보내기 버튼을 추가하는 확장 기능입니다. 별도로 구매할 필요 없이 저장소 안의 파일을 설치합니다. 기존 문서의 Blender MCP 애드온과는 별개이며, MCP 연결이나 Python 자동 실행 허용은 필요하지 않습니다.

### 1. 준비할 것

- **Blender 5.2 이상**을 설치합니다. 제공 원본은 Blender 5.2에서 저장했습니다.
- **최신 main이 반영된 LittleCast 저장소 clone 폴더**를 준비합니다. 애드온 파일 하나만으로는 원본·내보내기 도구·미리보기를 모두 사용할 수 없습니다.
- 설치 파일: `Tools/Art/aquarium_terrain/blender_addon.py`. [저장소에서 애드온 파일 확인](https://github.com/voidreader/LittleCast/blob/main/Tools/Art/aquarium_terrain/blender_addon.py) — 저장소 접근 권한이 있는 계정으로 열어 주세요.

### 2. 애드온 설치 — PC마다 한 번

1. Blender에서 **편집(Edit) → 환경설정(Preferences) → 애드온(Add-ons)**을 엽니다.
2. 애드온 화면 메뉴의 **디스크에서 설치(Install from Disk)**를 선택합니다.
3. clone 폴더의 `Tools/Art/aquarium_terrain/blender_addon.py`를 선택해 설치합니다.
4. 목록에서 **Little Cast 지형 JSON 내보내기**를 찾아 활성화합니다.
5. 지형 원본을 연 뒤 3D 화면에 마우스를 놓고 **N**을 누릅니다. 오른쪽 사이드바의 **Little Cast → 지형 내보내기**를 확인합니다.

애드온 파일이 업데이트되면 다시 설치하거나 Blender를 재시작하세요. 탭이 보이지 않으면 활성화 여부와 현재 영역이 3D View인지 확인합니다.

### 3. 테마 원본 열고 편집하기

| 테마 | 원본 경로 |
| --- | --- |
| 산호초 | `art/source/terrain/reef.blend` |
| 심해 | `art/source/terrain/deep.blend` |
| 계곡 | `art/source/terrain/valley.blend` |
| 북극 | `art/source/terrain/arctic.blend` |

1. Blender의 **파일 → 열기**에서 원하는 원본을 엽니다.
2. **지형 - 편집** 컬렉션의 바위·산호·바닥·유목 등을 수정합니다. 이동·회전·크기와 일반 메시 모디파이어가 반영됩니다.
3. 색은 **albedo 정점 색**을 수정합니다. Material Preview에서 확인할 수 있습니다. 일반 이미지 텍스처나 임의 셰이더만 바꾼 내용의 앱 반영은 보장하지 않습니다.
4. **생물 배치·충돌 - 이름 유지** 컬렉션은 생물 위치와 충돌 계산에 쓰입니다. 이름과 사용자 속성을 임의로 삭제하지 않습니다.

처음에는 기존 객체를 복제해 편집하면 필요한 정점 속성과 재질을 유지하기 쉽습니다. 새 Cube 등을 추가할 때는 아래 ‘편집 규칙’도 확인하세요. 북극 빙판·수면·생물은 이번 지형 편집 경로와 별개입니다.

### 4. 버튼으로 저장하고 JSON 내보내기

1. **Little Cast** 탭에서 테마가 맞는지 확인합니다.
2. **프로젝트 경로**는 보통 비워 둡니다. 원본 위치에서 저장소를 자동으로 찾습니다. 다른 위치의 원본 사본이라면 clone한 저장소의 맨 위 폴더를 지정합니다.
3. **굽기 표본 수**는 기본값 **64**로 둡니다.
4. **원본 저장 + JSON 내보내기**를 누릅니다. 현재 .blend를 저장하며 Edit 모드면 Object 모드로 전환합니다.
5. 상태가 **처리 중 → 완료**로 바뀔 때까지 기다립니다. 별도 Blender 프로세스가 조명 굽기·최적화·JSON 생성을 수행하며 편집 중인 개별 객체는 합쳐지지 않습니다.

**결과 저장 위치**

`aquarium_web/src/habitats/terrain/<테마>.json`

앱은 .blend를 직접 열지 않고 이 JSON으로 렌더링합니다. **.blend 저장만으로는 JSON이 갱신되지 않습니다.** 버튼으로 내보내기까지 완료해 주세요.

### 5. Mac·Windows 웹 미리보기에서 확인하기

1. 저장소 **맨 위 폴더**에서 Mac은 `미리보기-Mac.command`, Windows는 `미리보기-Windows.cmd`를 두 번 클릭합니다.
2. 브라우저가 열릴 때까지 기다리고 **실행 창은 열어 둡니다.** 최초 실행은 Flutter·Node.js 준비와 패키지 설치에 시간이 걸릴 수 있습니다. Blender는 별도 설치합니다.
3. 브라우저 위쪽 메뉴에서 **수족관**과 편집한 지역을 선택합니다.
4. Blender 내보내기 완료 후 JSON 변경을 감지해 **자동 재빌드 → 자동 새로고침**합니다. 빌드 완료까지 기다립니다.
5. 필요하면 실행 창에 **r 입력 후 Enter**로 재빌드합니다. 미리보기를 끄고 내보냈어도 다음 실행에서 반영됩니다. 종료는 **Ctrl+C**입니다.

미리보기는 clone한 소스로 실행하는 앱 화면이며, 이 문서 사이트 자체가 플레이 화면은 아닙니다. 실제 기기용 앱의 빌드·배포는 개발 담당자가 별도로 수행합니다.

### 6. 다른 작업자에게 전달하기

수정한 **.blend 원본과 내보낸 JSON을 함께** Git에 반영하거나 개발 담당자에게 전달합니다. 개발 담당자는 웹 번들 `assets/aquarium/index.html`을 재생성한 뒤 앱을 빌드·배포합니다. 다른 PC는 최신 저장소를 받은 뒤 그 PC의 실행 파일을 사용합니다. `.preview-tools/`나 빌드 폴더를 복사할 필요는 없습니다.

### 편집 규칙: 색·흔들림·발광·생물 표시 객체

- `mesh.static.<이름>`: 고정 지형. POINT/FLOAT_COLOR의 `albedo` 정점 속성과 Terrain 재질을 사용합니다.
- `mesh.sway.<이름>`: 수초. POINT/FLOAT `sway` 속성(0=뿌리, 1=끝)을 유지합니다.
- `mesh.glow.<이름>`: 발광 지형. POINT/FLOAT_COLOR `glow` 속성을 유지합니다.
- `mesh.logs.<이름>`: 통나무 형상. 크기를 바꾸면 통나무 표시점·반지름도 함께 수정합니다.
- `anchor.<종류>.<정수번호>`: 생물 자리. 종류는 anemone·floor·rock·seagrass·weed·vent입니다.
- `keepout.<정수번호>`: 생물이 비켜갈 영역. Empty 표시 크기가 반지름입니다.
- `log.<정수번호>.a`·`.b`: 통나무 양 끝. `r0`·`r1`·`capStart` 속성을 유지합니다.
- 심해의 `mark.mouth`·`mark.smallMouth`는 필수 표시점이므로 삭제하거나 이름을 바꾸지 않습니다.
- 표시 객체를 복제하면 `.001` 접미사를 그대로 두지 말고 정수번호를 새로 부여합니다.
- 편집 중 숨기거나 선택 잠금한 지형도 내보내기 대상입니다. 작업용 메시를 장면에 남기지 마세요.
- 고밀도 모디파이어는 앱의 폴리곤 수를 늘립니다. 일반 텍스처·임의 셰이더를 그대로 앱에 가져오는 기능은 포함하지 않습니다.

### 문제가 생기면

| 증상 | 확인할 것 |
| --- | --- |
| Little Cast 탭이 안 보임 | 애드온 활성화, Blender 버전, 3D View에서 N 키로 사이드바를 열었는지 확인합니다. |
| 프로젝트를 못 찾음 | 저장소의 원본을 열거나 프로젝트 경로에 clone 폴더를 지정합니다. |
| 내보내기 실패 | Blender 사이드바와 `.preview-tools/terrain-export/<테마>.log`를 확인합니다. 속성·표시점 오류를 고친 뒤 다시 내보냅니다. 실패하면 기존 정상 JSON을 유지합니다. |
| 웹에서 그대로 보임 | JSON 내보내기 완료를 확인합니다. 미리보기 실행 창에서 r + Enter로 재빌드하고 브라우저의 지역 선택을 확인합니다. |
| 웹 빌드 실패 | 미리보기 실행 창의 오류를 개발 담당자에게 전달합니다. 마지막 정상 화면을 유지하며 다음 수정 후 다시 빌드할 수 있습니다. |
| 다른 저장소에 출력됨 | 별도 원본 사본을 사용한다면 프로젝트 경로가 현재 작업할 clone을 가리키는지 확인합니다. |

[Blender 작업 안내 내려받기 (.md)](/blender-terrain.md)

[저장소의 최신 지형 작업 안내](https://github.com/voidreader/LittleCast/blob/main/Tools/Art/aquarium_terrain/README.md)

**원문의 전환 검증 기록:** 네 테마의 출력 JSON이 기존 파일과 바이트까지 동일함을 확인했습니다. Blender 통합 시험·웹 시험 733개·전체 Flutter 웹 미리보기 빌드를 확인했습니다. Windows 환경의 직접 실행과 신규 시각 비교는 별도로 수행하지 않았습니다. 화면·성능 기록은 [수족관 개선 기록](/aquarium-improvement/)의 역사적 검수 자료이며 이번 문서 반영에서 재실행하지 않았습니다.

## 문서 반영 시 대조한 제작 계약

- `albedo`는 POINT 도메인의 `FLOAT_COLOR`, `sway`는 POINT/FLOAT, `glow`는 POINT/FLOAT_COLOR 속성이다.
- 관련 Empty는 부모가 있어도 월드 좌표를 쓴다. `keepout` 반지름은 Empty 표시 크기에 월드 XY 크기를 반영한다.
- 조명·World는 원본에 저장된 값을 사용하며 굽기 밝기는 Scene의 `littlecast_terrain_look` 안 `exposure`·`light_floor`로 보정한다.
- 기존 파일을 `--create-source`로 재생성하지 않는다. 개발자 일괄 내보내기와 세부 검사는 [저장소 제작 안내](https://github.com/voidreader/LittleCast/blob/78975e2/Tools/Art/aquarium_terrain/README.md)를 따른다.

이 문서의 브라우저 미리보기는 앱 화면용이다. **기획서 자체**를 읽을 때는 `DocsSite/start-docs.command` 또는 `DocsSite/start-docs.cmd`를 실행한다. macOS·Windows 작업 방법을 설명하지만 이번 반영에서 두 운영체제의 앱 미리보기·Blender 실행을 재검증한 것은 아니다.