Blender 지형 작업 안내

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

수족관 개선 공유 문서의 Blender 안내를 반영하고, 저장소 Tools/Art/aquarium_terrain/README.md와 대조했다. 아래는 제작 방법이며 이번 작업에서 Blender·앱·Windows를 실제 실행한 검증 기록이 아니다. 당시 수족관 개선 기록도 함께 볼 수 있다.

추가 안내 · 2026.10.25

Blender에서 지형 수정하기

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

main 반영 01d5929 · 지형 원본 전환과 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. 저장소에서 애드온 파일 확인 — 저장소 접근 권한이 있는 계정으로 열어 주세요.

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

Blender에서 **편집(Edit) → 환경설정(Preferences) → 애드온(Add-ons)**을 엽니다.
애드온 화면 메뉴의 **디스크에서 설치(Install from Disk)**를 선택합니다.
clone 폴더의 Tools/Art/aquarium_terrain/blender_addon.py를 선택해 설치합니다.
목록에서 Little Cast 지형 JSON 내보내기를 찾아 활성화합니다.
지형 원본을 연 뒤 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`

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

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

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

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

결과 저장 위치

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

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

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

저장소 맨 위 폴더에서 Mac은 미리보기-Mac.command, Windows는 미리보기-Windows.cmd를 두 번 클릭합니다.
브라우저가 열릴 때까지 기다리고 실행 창은 열어 둡니다. 최초 실행은 Flutter·Node.js 준비와 패키지 설치에 시간이 걸릴 수 있습니다. Blender는 별도 설치합니다.
브라우저 위쪽 메뉴에서 수족관과 편집한 지역을 선택합니다.
Blender 내보내기 완료 후 JSON 변경을 감지해 자동 재빌드 → 자동 새로고침합니다. 빌드 완료까지 기다립니다.
필요하면 실행 창에 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)

저장소의 최신 지형 작업 안내

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

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

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로 재생성하지 않는다. 개발자 일괄 내보내기와 세부 검사는 저장소 제작 안내를 따른다.

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