수족관 개선 기록 · 2026-10-25

상태: 과거 개선 작업 기록 · 기록 기준: 2026-10-25 · 문서 반영: 2026-11-01

수족관 개선 작업 공유 원문의 내용을 이관했다. 아래 성능·시험·리뷰 수치는 원문의 당시 기록이며 이번 문서 작업에서 앱 검증을 다시 수행한 결과가 아니다. 원문에 쓰인 ‘현재’와 ‘남은 과제’도 해당 기록 시점을 뜻한다.

현재 작업에 적용할 때

후속 작업의 최종 물빛·윤슬·코스틱·기포·얼음 표현은 수족관 물과 빛 · 최종 적용 결과에서 확인한다.
움직임 궤적 기록은 현재 플랫폼·CPU별 기준 파일을 쓴다. 지원 환경과 갱신 절차는 저장소 README를 확인하고, 과거의 단일 갱신 명령을 모든 환경의 검증 완료로 해석하지 않는다.
지형 편집은 후속 원본 전환 커밋 01d5929의 Blender 지형 작업 안내를 따른다. themes/는 최초 제작용이고 편집한 원본을 다시 생성하지 않는다.
아래의 ‘수면 아래로는 내려가지 않음’과 눈 높이 0.8~1.6 제한은 당시 계약이다. 이후 Ruling 95 기준 산호초·계곡·북극은 4°까지 낮춰 수면 아래 시점을 허용하고, 심해는 눈이 수면 위 0.3에 오는 하한을 유지한다. 현재 입력은 수족관과 생물과 저장소 core/camera-view.ts를 따른다.
산호초 물 높이 11→10은 당시 변경이며 이번 확인에서도 REEF_BLOCK.waterHeight = 10이다. README에 남은 11 표기와 구분하고 실제 치수는 scene/block-dimensions.ts를 확인한다.
원문의 ‘Tripo 미사용’은 이 개선 작업의 범위다. 현재 프로젝트에는 앞선 작업의 Tripo 기반 정점색 동물 자산이 함께 있다. Blender MCP 구버전 안내 역시 당시 환경 기록으로, 현재 버전을 점검한 결과가 아니다. 지형 내보내기 애드온은 MCP와 별개다.
미완료 항목은 구현 현황과 저장소 docs/follow-ups.md에서 최신 상태를 확인한다. 과거 검수의 승인·완료를 새 변경으로 확대하지 않는다.

개선 작업 요약

2026-10-25 당시 main 병합·푸시 완료. 네 개의 수족관을 시안에 더 가깝게 개선했다.

지형과 물빛을 다듬고, 시점을 움직이고, 생물이 몸을 휘며 헤엄치도록 개선했습니다.

기획 웹문서와 산호초·심해·계곡·북극 시안 4장을 기준으로 진행한 작업입니다. 팀원이 바뀐 부분과 검증 범위, 이어서 할 일을 빠르게 파악할 수 있도록 정리했습니다.

작업일 2026.10.25 병합 커밋 efd1772

작업 브랜치 codex/aquarium-concept-match

4개 테마: Blender 지형 자산 전환
120장: 테마별 웹 검수 기록
58~60 fps: 당시 실기기 고품질 중앙값

앱 검증 수치는 원본에 기록된 병합 시점 결과입니다. 이번 웹문서 제작에서 앱 검증을 다시 수행한 것은 아닙니다.

무엇이 달라졌나

화면 표현부터 조작과 움직임까지

영역	무엇을 바꿨나
지형	네 수족관의 바닥·바위·산호·유목을 Blender 스크립트로 만들고, 빛을 정점 색에 구워 웹 자산으로 내보낸다
시점	한 손가락 세로 드래그로 카메라 높이각을 바꾼다(수면 아래로는 내려가지 않음)
물빛	높이에 따른 물빛 그라데이션, 햇빛 쪽 밝힘, 유리 모서리 반사
Emission	수면·햇빛 쪽 물이 은은하게 빛나고, 유리 모서리와 수면 가장자리에 빛이 번진다(아트 담당 요청)
빛	빛줄기의 갈매기 무늬를 없애고 수면에서 넓게 퍼지게 바꿈. 바닥 물결 빛을 넓고 옅게
생물 움직임	방향을 틀 때 몸이 휨. 산갈치·대형 포유류는 몸 전체 물결로 헤엄. 수달은 수면에서 헤엄치다 가끔 잠수
심해	앞 모서리의 뿌연 띠 제거, 약한 수면 반사, 열수구 굴뚝 두 개
산호초	물 높이를 11에서 10으로 낮춤(시안의 정육면체 비율)
예산	삼각형 한도를 고품질 300,000·저품질 150,000으로 올림. 그리기 호출 한도는 100/60 그대로(사용자 승인)
검수 도구	시안과의 색 차이 측정 도구, 테마별 웹 검수 캡처, Android 실기기 검수 스크립트

구현 방식의 핵심

지형은 Blender에서 조형하고 빛을 정점 색에 구워 고·저품질 공용 자산으로 전환했습니다. 수면과 모서리의 추가 발광은 물빛이 바래는 것을 피하기 위해 후처리 블룸 대신 물 셰이더로 구현했습니다.

수족관·근접 보기의 톤매핑은 분리 설정할 수 있도록 연결만 만들었으며, 실제 값은 네 테마 모두 ACES·노출 1을 유지했습니다. 심해의 기존 블룸·생물 발광·빛 무늬 값도 유지했습니다.

네 테마 살펴보기

기존 검수 자료로 확인하는 변화

이미지 순서: 시안 → 작업 결과(높이각 14°) → 변경 전. 누르면 원본 크기로 열립니다. 아래는 기존 앱 검수 자료이며 이 웹문서의 신규 화면 검수가 아닙니다.

산호초

양옆의 큰 산호 군락과 모래 공터. 시안 비율에 맞춰 물 높이를 11에서 10으로 낮췄습니다.

웹 검수 판 보기 · Android 실기기 판 보기

심해

어두운 암반에 열수구 굴뚝 두 개를 배치했습니다. 앞 모서리의 뿌연 띠를 제거하고 약한 수면 반사를 더했습니다.

웹 검수 판 보기 · Android 실기기 판 보기

계곡

바위·이끼·굵은 유목·자갈 물길과 물풀을 조형했습니다. 유목 아래는 통로를 열어 두고, 수달의 수면 헤엄과 잠수를 적용했습니다.

웹 검수 판 보기 · Android 실기기 판 보기

북극

회백 모래와 푸른 회색 바위 사이에 넓은 유영 공간을 두었습니다. 바닥만 Blender로 전환했으며 빙판은 기존 웹 코드를 유지합니다.

웹 검수 판 보기 · Android 실기기 판 보기

검증 결과

2026.10.25 병합 시점 기록

항목	결과
웹 시험	`cd aquarium_web && npx tsc --noEmit && npm test` → 733 통과
매트릭스 캡처	`node scripts/capture.mjs --matrix` 종료 0. 고품질 최대 222,640면·39호출, 저품질 111,261면·20호출
테마별 웹 검수	네 테마 × 30장(기본·높이각 한계·회전·확대·저품질·태블릿·대표 선택·60초 헤엄). 예산·콘솔·셰이더 오류 없음, 전환 20회 GPU 자원 같음
시안 색차(CIEDE2000)	네 테마 고·저 모두 합격. 고품질 최대 ΔE: 산호초 6.9·심해 10.3·계곡 10.6·북극 10.1(합격선: 물 9, 나머지 12)
Flutter	`flutter analyze` 문제 없음, `flutter test` 406 통과
Blender 재현	네 테마 다시 내보내기 → 커밋된 JSON과 바이트 같음
번들	3.05MB(상한 4MB)
실기기	Android SM-S908N. 네 테마 진입·가로/세로 드래그·두 손가락 확대·대표종 탭·전환·백그라운드 복귀 확인. 30초 fps 중앙값 고품질 58~60, 저품질 58
최종 독립 리뷰	Critical 0. 지적 Important 2·Minor 10은 반영하거나 follow-up으로 기록

기록 차이: 보조 결과 노트에는 웹 시험 734개가 기록되어 있습니다. 이 문서는 요청된 인계 문서의 733개를 기준으로 기재하며, 기록 간 차이를 확정하지 않았습니다.

남은 과제와 알려진 한계

완료한 개선과 구분해 이어갈 일

저사양 기기 성능은 아직 확인하지 않았습니다.

실기기 검수는 상위 Android 기종 SM-S908N 한 대에서 수행했습니다. 기록된 fps를 다른 기기의 성능으로 일반화할 수 없습니다.

저사양 기기 성능 미검증. 실기기는 상위 기종 한 대뿐이다. 지형 자산으로 번들이 커져 검수 앱 시작 시간이 3,023ms에서 3,313ms로 늘었다.
도감 PNG 7종 정지 자세 차이. 헤엄을 바꾼 산갈치·장어·주름상어·벨루가·일각고래·턱수염물범·수달은 다시 내보내면 자세가 조금 다르다(식별 차이 없음). 도감 이미지는 다시 만들지 않았다. 나머지 41장은 바이트까지 같다.
고품질 심해의 블록 뒤 사각형 배경. 블룸 출력 패스가 배경을 단색(#91d3fa)으로 채우는데 앱 배경은 그라데이션이라 경계가 보인다. main부터 있던 동작이다.
물 셰이더 NaN의 근본 원인 미추적. 지금은 출력에서 막고 있다.
3배 확대 시 블록 앞 모서리 세로 이음선. 예전부터 있던 투과 재질 결함이다.
Tripo 미사용. 필요하면 HD 모델로만 생성하고 스마트메쉬는 쓰지 않으며, Playwright로 웹을 조작한다(사용자 조건).
Blender MCP 애드온 구버전. 헤드리스 재생성에는 지장이 없다. Blender 화면을 보며 다루려면 uvx mcp-for-blender install-addon으로 갱신한다.

1~5는 docs/follow-ups.md에 자세히 있다.

개발자 인계

다음 변경 전에 확인할 경로와 기준

현재 지형 편집: art/source/terrain/<테마>.blend를 수정한 뒤 Blender 내보내기 버튼을 사용한다. 생성 스크립트는 최초 원본 제작용이며 개발자는 JSON으로 웹 번들을 재생성한다.
새 수족관: README “새 수족관·새 종 추가”를 따른다. 지형은 Blender 원본 → JSON → buildTerrain·terrainAnchors, 조명·해제는 habitat-kit.ts의 createHabitatLights·disposeHabitat.
물 굴절률 WATER_IOR = 1.02는 바꾸지 않는다. 1.33이면 생물이 여러 겹으로 보이고 탭 위치와 어긋난다.
심해 빛 표현(블룸·생물 발광·빛 무늬)은 사용자 결정으로 고정이다. 공용 셰이더 상수를 바꾸면 심해 캡처를 변경 전과 대조한다. 심해 장식 발광 정점은 819개 상한 시험이 지킨다.
셰이더 패치는 onBeforeCompile 문자열 치환이다. 문자열이 갈리면 customProgramCacheKey나 chainShaderPatch 키도 갈라야 한다.
프레임마다 객체를 만들지 않는다. 수족관·품질을 바꿀 때는 GPU 자원을 해제한다.
움직임 코드를 바꾸면 궤적 기록 시험(tests/motion-trace.test.ts)이 비트 단위로 잡는다. 의도한 변경일 때만 UPDATE_MOTION_TRACE=1로 다시 만들고 커밋에 이유를 적는다.

당시 검수 도구

테마 웹 검수: node Tools/Visual/capture_concept_match.mjs <테마> <출력 폴더>
시안 색차: cd aquarium_web && node scripts/color-match.mjs --theme all --capture-dir <폴더> [--quality low] [--overlay] (기준 docs/verification/aquarium-concept-match/color-targets.json, 합격선을 넘으면 종료 코드 1)
실기기: 검수 앱(flutter build apk --debug -t Tools/Visual/approved_reef_main.dart)을 설치하고 adb forward tcp:18765 tcp:18764를 건 뒤 node Tools/Visual/capture_concept_match_android.mjs <serial> <출력 폴더>. 끝나면 일반 앱을 다시 설치한다.
생물 없이 보기: ?creatures=0
Android 검증은 승인된 실기기만 쓴다(에뮬레이터 금지).

지형 자산 파이프라인·내보내기 명령

현재는 art/source/terrain/<테마>.blend가 편집 원본이다. 저장된 원본을 별도 Blender 프로세스에서 읽고 Cycles로 빛을 정점 색에 구워 JSON으로 내보낸다. 아래 themes/는 최초 원본 제작 도구이며 일반 내보내기에서 다시 실행하지 않는다.

편집 원본: art/source/terrain/
애드온·내보내기 도구: Tools/Art/aquarium_terrain/
common.py: 좌표 변환과 조형 함수(바위·산호·수초·유목·바닥)
bake.py: 빛 굽기
export.py: 메시 합치기, 높이 격자, 표시 객체 내보내기
heightfield.py: 생물이 걸리지 않게 다듬은 높이 덮개
encode.py: JSON 인코딩
themes/{reef,deep,valley,arctic}.py: 테마별 조형
사용법과 이름 규칙: README.md
결과 자산: aquarium_web/src/habitats/terrain/<테마>.json. 고품질·저품질이 같은 자산을 쓴다. 손으로 고치지 않는다.
웹 로더: aquarium_web/src/habitats/terrain-asset.ts가 디코드·메시·높이 격자·앵커·비켜 갈 기둥·통나무 마디를 읽는다. 구운 빛 재질은 aquarium_web/src/scene/baked-light.ts.
지형은 시드와 무관하게 고정이다. 시드는 생물에만 쓴다.
다시 만들기(같은 명령은 바이트까지 같은 결과를 낸다):

/Applications/Blender.app/Contents/MacOS/Blender -b --factory-startup --python-exit-code 1 --python Tools/Art/aquarium_terrain/run.py -- \
--theme all --out aquarium_web/src/habitats/terrain
cd aquarium_web && npm run build   # 앱 번들에 넣고 함께 커밋한다

테마별 지형

테마	내용
산호초	양옆의 큰 산호 군락, 앞쪽은 모래 공터. 말미잘은 모래 위 (0.3, 1.6)
심해	왼쪽 뒤 어두운 암반에서 높이가 다른 열수구 굴뚝 둘이 솟는다(입구는 호박빛 발광). 보라 관벌레·흰 유리해면·흰 가지산호. 앞쪽은 옅은 격자 무늬 퇴적지. 열수구 위치 (-2.3, -1.7)
계곡	회색 바위와 이끼, 바위에 기댄 굵은 유목, 자갈 물길 둑, 물풀 무리, 주황 갈색 지층. 유목은 별도 메시(`terrain:log`)라 아래 통로가 열려 있다
북극	회백 모래 위 양옆에 푸른 회색 다면체 바위, 가운데는 넓은 유영 공간. 빙판은 웹 코드(`scene/ice-floes.ts`) 그대로이고 바닥만 Blender다

세로 드래그와 카메라 제한

한 손가락으로 좌우로 끌면 회전, 위아래로 끌면 높이각이 바뀐다. 아래로 끌면 내려다보는 쪽이다.
드래그를 시작할 때 더 많이 움직인 축이 주 축이다. 다른 축은 누른 곳부터의 이동이 주 축의 0.35배(AXIS_LOCK_RATIO) 이상일 때만 반영한다.
누른 곳부터 세로 20px(ELEVATION_DEAD_ZONE_PX)까지는 높이각을 바꾸지 않는다. 탭하려다 손가락이 미끄러져도 블록이 기울지 않게 하려는 것이다.
당시 아래 한계: 카메라 눈이 수면보다 0.8 위에 있는 높이각. 확대할수록 여유가 1.6까지 늘어 확대해도 수면 아래가 보이지 않는다.
당시 위 한계: 60°
수족관을 바꾸면 테마 기본 높이각으로 돌아가고 관성도 사라진다. 근접 보기는 높이각이 고정이다.
코드: aquarium_web/src/core/orbit-drag.ts, core/camera-view.ts(minElevationDeg·elevationLimits·fitCameraElevation), core/aquarium-app.ts
검수용 URL 파라미터: ?pitch=<도>. 0은 아래 한계이고, 시안과 비슷한 시점은 14다.

물빛·Emission·심해·셰이더 방어

물 설정은 수족관별 WaterStyle(aquarium_web/src/scene/water.ts)이고, 값은 각 habitats/<테마>.ts에 있다. 셰이더는 scene/water-shaders.ts와 water-transmission-material.ts(고품질)·water-fake-material.ts(저품질)다.

물빛 그라데이션: 물 안쪽 벽(backdrop)에 가운데 색(mid·midAt)과 햇빛 쪽 밝힘(sunBoost·sunColor)을 더했다. 안쪽 벽은 톤매핑을 받지 않게 해서 저품질 물빛을 고품질과 맞췄다.
유리 모서리(glassEdge): 블록 외곽 모서리의 얇은 유리 반사(폭 0.05)다. 예전에 없앤 “물 경계 흰 선”과는 다른 요소다.

Emission(아트 담당 요청)

(b) WaterStyle.emission: 물 높이 위쪽 30%부터 수면까지, 그리고 해 쪽(블록 -x)일수록 은은하게 빛난다. 세기는 산호초 0.06, 계곡·북극 0.035.
(c) glassEdge.glow·glowWidth: 유리 모서리·수면 가장자리 둘레 0.3 폭으로 부드럽게 사라지는 빛 번짐(0.24).
후처리 블룸이 아니라 물 셰이더로 구현했다. 블룸을 켜면 출력 단계에서 모든 화소에 톤매핑이 걸려 물빛 전체가 바랬기 때문이다. 고품질·저품질 모두 적용되고 그리기 호출은 늘지 않는다.
심해에는 넣지 않았다(심해 빛 표현 고정 결정).

심해

모서리 맑음 폭을 edgeFade 0.12로 좁혀 앞 모서리의 뿌연 띠를 없앴다.
물빛 색을 시안 남색으로 낮췄다.
약한 수면 반사(0.08, 반짝임 0.25)를 사용자 허용으로 더했다.
블룸·생물 발광·빛 무늬 값은 그대로다.
톤매핑: 수족관 화면과 근접 보기를 따로 정할 수 있는 연결(aquariumToneFor, AquariumApp.setToneMapping)만 만들었다. 값은 네 테마 모두 ACES·노출 1 그대로다.
물 셰이더 NaN 방어: 수면을 아주 낮은 각도로 스치면 먼 가장자리에서 NaN 색이 나오고, 심해에서는 블룸이 이것을 화면 전체로 번져 장면이 사라졌다. 지금은 출력에서 물빛으로 바꿔 막는다. 근본 원인 추적은 follow-up이다.

빛줄기·바닥 물결 빛

빛줄기(scene/light-shafts.ts): 줄기의 옆 방향을 수면 시작점(aOrigin) 하나로 구해 가장자리를 곧게 했다. 해 쪽 수면에서 넓게 시작해 아래로 퍼지며(spread 1.8) 길이의 67%까지 서서히 사라진다(fadeEnd).
내려다보는 시점에서는 옆면이 보이는 정도에 따라 약해진다.
산호초·계곡·북극에 쓴다.
바닥 물결 빛(scene/caustics.ts): 대비(contrast)와 깊이 감쇠(depthFade) 옵션을 더해 바닥과 지층 윗면에 넓고 옅게 깐다. 지층(strata.ts)도 수족관의 빛 무늬 값을 따른다. 심해는 그대로다.

종별 움직임과 수달 잠수

회전 휨: 에이전트에 회전·상승 속도(turn·climb)를 두고, 인스턴스 속성 iTurn과 셰이더 uSwimBend로 방향을 틀 때 몸이 회전 쪽으로 휜다.
헤엄 재질 캐시 키는 swim-v4-다.
근접 보기에도 적용된다.
산갈치·대형 포유류(벨루가·일각고래·턱수염물범 등): buildAuthoredAnimal(data, swim)이 종별 헤엄 값을 받아 몸 전체 물결로 헤엄친다. 장어·주름상어에도 같은 리본 가중치가 적용됐다.
수달: 새 헤엄 계열 종류 surface(motion/kinds.ts 표 한 줄 + 특성 surfaceSwimmer·dive, 동작은 motion/surface.ts)다.
수면 바로 아래(몸 중심이 수면 - 0.12)에서 헤엄친다.
20~~35초마다 4~~8초 동안 잠수했다가 떠오른다.
물 영역에 수면 높이 WaterBounds.surfaceY를 더했다.
잠수 난수는 dive 특성이 있는 종만 쓰므로 계곡 외 수족관의 움직임 궤적은 바뀌지 않았다.

원본과 출처

상세 절차와 판단 근거 찾기

원본 인계 문서 내려받기 (.md)

이 페이지는 docs/results/2026-10-25-aquarium-improvement-handoff.md를 바탕으로 재구성했습니다. 아래는 저장소에서 찾을 수 있는 경로입니다.

설계서 docs/superpowers/specs/2026-10-25-aquarium-concept-match-design.md
구현 계획 docs/superpowers/plans/2026-10-25-aquarium-concept-match.md
보조 결과 노트 docs/results/2026-10-25-aquarium-concept-match-notes.md
판단 기록 (Ruling 74~90) docs/decisions-log.md
검수 증거 docs/verification/aquarium-concept-match/
후속 과제 docs/follow-ups.md

기존 개선 기록에 Blender 원본 편집·내보내기 안내를 추가했습니다. 이후 저장소 변경 사항은 자동 반영하지 않습니다.

이번 문서 반영의 확인 범위

비교 이미지 4장과 웹·Android 검수 판 8장은 저장소 docs/verification/aquarium-concept-match/의 기존 파일을 그대로 복사했다. 새 캡처나 시각 비교를 수행하지 않았다. 이번 반영은 원문 내용·이미지 참조·정적 HTML/Markdown·링크 검증을 대상으로 하며 앱 기능 변경·기기 시험·현재 성능 측정·배포는 포함하지 않는다.

현재 기준을 확인한 저장소 파일

저장소 링크는 비공개 저장소 권한이 필요하다. 권한 있는 로컬 저장소의 같은 경로로도 확인할 수 있다.