# 힐링 레퍼런스 젤리 세 종류

## 목적과 사용자 선택

`references/HealingJelly/`의 1번, 2·3번(한 종류), 5번을 플레이 가능한 힐링 젤리로 만든다. 비현실적인 외형과 내부의 깊이, 잘랐을 때 발견하는 아름다운 속살이 목적이다. 첫 절단뿐 아니라 누운 조각의 재절단에서도 같은 입체 무늬가 이어진다.

사용자는 **기존 입체 절단에 3D 절차 재질을 결합하는 방식**과 **Superpowers 전체 시각 검수**를 선택했다. 사용자는 5번을 레퍼런스 형태 그대로 별도 구현하고 기존 용과를 유지하는 수정 설계를 승인했다. 2026-11-01 별도 브랜치에서 Native로 실행한다.

## 검토한 구현 방식

1. **3D 절차 재질 — 사용자 선택.** 원본 좌표에서 색·밀도·포함물을 계산하고 현재 조각 안의 깊이를 제한하여 그린다. 임의의 절단·회전·재절단과 연결되며 기존 절단 메시와 비늘 분할을 활용한다. 재질의 색과 빛은 캡처를 보며 조정해야 한다.
2. **볼륨 텍스처 자산 제작.** 미리 제작한 입체 색·밀도장을 샘플링한다. 무늬의 위치를 세밀하게 저작할 수 있지만 자산 제작·메모리·필터링 관리가 추가된다. 이번 세 종류는 절차적 구름층과 입자로 표현할 수 있어 선택하지 않았다.

## 종류별 외관과 속살

| 종류 | 기준 이미지 | 절단 전 | 절단 후 |
| --- | --- | --- | --- |
| 은하 젤리 / Galaxy Jelly | `HealingJelly_1.png` | 아래가 안정적으로 놓이는 둥근 구체. 맑은 연보라 바탕 속에 분홍·청색 성운, 금색·은색·청색 미세 반짝이가 깊이를 달리하며 모여 있다. 젖은 광택과 부드럽고 넓은 조명 반사가 보인다. | 내부에서 성운의 밀도와 색층이 더 선명해진다. 절단 위치에 따라 다른 구름 단면과 반짝이 분포가 드러난다. 표면에도 얇은 촉촉한 막이 남는다. |
| 오팔 젤리 / Opal Jelly | `HealingJelly_2.png`, `HealingJelly_3.png` | 둥근 구체에 우윳빛 반투명층과 분홍·라일락·하늘·민트색이 넓게 번진다. 금속이나 거울처럼 보이지 않으며 작은 반짝이는 넣지 않는다. | 3번처럼 바깥은 옅고 부드럽고, 안쪽에는 청록·보라·분홍의 조금 더 선명한 휘어진 색층이 드러난다. 불투명한 흰 덩어리나 딱딱한 동심원 무늬로 만들지 않는다. |
| 5번 비늘 젤리（식별용 임시 명칭） | `HealingJelly_5.png` | 끝이 좁아지는 타원형의 장밋빛 투명 몸체. 표면을 감싼 겹겹의 비늘 같은 판, 판 사이의 또렷한 경계와 연두색 끝, 몸체 안의 작은 기포가 보인다. 특정 과일로 단정하지 않고 사진의 윤곽과 판 구조를 기준으로 만든다. | 맑은 분홍 속살과 기포를 기본 제안으로 한다. 레퍼런스에는 단면이 없으므로 내부 디자인은 사진에서 확인한 사실과 구분한다. 과육·씨앗은 추가하지 않는다. 비늘 같은 표면 판도 실제 절단 평면에서 나뉜다. |

은하와 오팔의 둥근 하부·상부는 새 높이 프로필로 만든다. 도마 접촉부는 안정적으로 보이게 하고, 기존 오로라의 높은 반구 형상을 그대로 재사용하지 않는다. 정확한 반경·높이와 색상·밀도·광택 수치는 구현자가 두 해상도에서 조정한다. 5번은 기존 용과 형상이나 돌출 잎 구조를 정답으로 간주하지 않는다. 레퍼런스의 끝이 좁아지는 몸체와 몸체를 감싸는 표면 판 구조를 별도로 설계한다. 기존 비늘 절단 코드는 적합한 연산만 재사용할 수 있다.

손·칼·배경을 포함한 사진 전체의 복제는 범위가 아니다. 레퍼런스의 조형·색·투명감·내부 대비를 현재 게임의 도마와 카메라에서 읽히게 만든다. 별도의 자동 전시 회전이나 새 게임 조작을 추가하지 않는다.

## 편성·저장·이름

5번을 기존 용과로 단정했던 초안은 사용자 지적에 따라 철회했다. 수정 제안은 기존 206판 `healing-dragon-fruit`와 207판 `healing-aurora`를 유지하고, 뒤에 208판 은하(`healing-galaxy`), 209판 오팔(`healing-opal`), 210판 5번 비늘 젤리를 추가하는 것이다. 5번은 크리스털 비늘 젤리 / Crystal Scales, 고유 ID `healing-crystal-scales`로 식별한다. 2·3번은 동일 종류·동일 스테이지다. 기존 완료·별·도감 기록을 다른 종류로 해석하지 않는다. 사용자가 이 수정 설계로 세 종류 구현을 승인했다. 5번의 내부는 사진에서 확인할 수 없으므로 투명한 분홍 속살과 기포로 구현한다.

새 스테이지는 고유 ID를 사용하고 표시 순서는 `src/stages/stage-order.json`에서 정한다. 기존 ID·기존 순서·`legacy-stage-order.json`을 수정하지 않는다. 신규 종류를 도감·메뉴·미리보기·일반 젤리 재질 레지스트리·퍼즈 묶음과 연결하며 각 위치에서 해당 종류의 색과 정체성을 알아볼 수 있어야 한다. 플레이의 입체 무늬 좌표 계약은 전용 힐링 장면이 소유한다.

신규 이름은 `src/i18n/texts.csv`에서 영어·한국어를 함께 등록한다. 자동 생성 JSON을 직접 편집하지 않는다. 첫 단면 발견 시 고정 3별을 한 번 저장하고 이후에는 수동 이동하는 기존 규칙을 유지한다.

## 렌더링과 절단 연결

- `HealingGeometry`·`HealingRender`에 새 종류의 형상·재질을 추가한다. 기존 용과·오로라의 구별을 단순한 두 갈래 기본값에 맡기지 않고 새 종류를 명시적으로 처리한다. `Game`에 종류별 분기를 추가하지 않는다.
- 공통 3D 색·밀도·입자 함수는 변형 전 원본 좌표를 사용한다. 조각 이동·기울기·눌림·늘어남이 무늬의 좌표를 바꾸지 않는다. 한 쌍의 절단면에서는 표면의 무늬가 이어지고, 각 면에서 더 깊게 보이는 부분만 시선 방향에 따라 달라진다.
- 외피와 단면은 같은 내부장을 사용하되, 외피는 두께·산란으로 부드럽게 보이고 단면은 내부 색과 포함물이 읽히도록 한다. 반사광이 단면을 흰색으로 덮거나 투과도가 높아 색이 사라지지 않게 별도 강도를 조정한다.
- 내부의 짧은 시선 적분을 도입할 때 원래 입체의 경계와 현재 조각의 모든 유효 절단 반공간을 함께 적용한다. 누운 조각의 재절단도 원본 공간으로 변환된 같은 평면 정보를 쓴다. 제거된 영역의 성운·색층·기포가 다시 나타나거나 도마 바깥까지 샘플링되지 않아야 한다.
- 절단 평면 정보의 전달 형식은 구현자가 선택한다. 반복 절단 횟수가 늘었다는 이유로 재질 프로그램이 매번 재컴파일되거나, 고정 개수를 넘는 평면을 조용히 버리는 구현은 금지한다. 조각별 유니폼·필요한 텍스처의 생성·준비 취소·인계·해제 책임을 명확히 둔다.
- 반짝이는 입체에 고정된 분포이며 시선·빛에 따라 밝기가 달라진다. 시간마다 무작위 위치를 다시 뽑거나 화면 전체에 반짝이 효과를 덧씌우지 않는다. 미세 입자는 화면 미분 등을 사용해 모바일에서 심한 점멸과 모아레가 생기지 않게 한다.
- Three.js의 기존 물리 재질·환경 조명을 활용한다. 추가 조명이나 반사 보조가 필요하면 힐링 장면에 한정하고 나갈 때 정리한다. 다른 모드의 조명·재질 기준을 바꾸지 않는다.

## 조작과 성능

세 종류 모두 기존 한 손가락 평행 이동·두 손가락 회전·마지막 손 해제로 확정·위아래 깊이 조절·자동 벌림·조각 선택 재절단을 제공한다. 긴 식칼, 손잡이 여유 공간, 조각 배치, 취소·숨김·컨텍스트 손실 처리를 유지한다. 새 구체의 실제 높이와 카메라 맞춤을 반영하여 칼·조각·조준점이 잘리지 않게 한다.

무늬를 위해 수천 개의 독립 메시를 만들지 않는다. 입자와 구름은 재질 안에서 표현하고 깊이 적분 횟수는 제한한다. 조준·입력 처리 안에서 무거운 메시나 텍스처를 동기 생성하지 않으며 기존 프레임 분할 준비를 유지한다. 첫 절단과 재절단의 새 셰이더 컴파일 유무, 초기 준비 시간, 정지·절단·벌림 구간의 프레임 시간을 기록한다. 기존 품질·메시·성능 테스트의 임계값을 낮추지 않는다.

## 검증과 시각 검수

사용자 선택은 **전체 시각 검수**다. 기본 캡처 범위는 모바일 390×844와 데스크톱 1280×800, 세 종류 각각 절단 전·첫 단면 벌림 완료·다른 위치의 재절단 완료로 **기본 18장**이다. 실제 입력 경로에서 중간 절단의 눌림·기포·비늘 잘림은 필요한 순간을 추가 기록한다. 품질 저하 등급에서도 세 종류의 정체성과 셰이더 정상 출력을 확인하며, 범위가 크게 늘어나면 추가 실행 전에 알린다.

구현자가 레퍼런스와 캡처를 대조하고 수정·재촬영한다. 최종 독립 리뷰는 `gpt-6.1-sol` / `medium`을 명시하여 코드·캡처·검증 기록을 함께 검토한다. 캡처 스크립트와 결과는 `.playwright-mcp/healing-reference-jellies/`에 둔다.

필수 기능 검증은 새 형상의 유한한 정점·법선·닫힘과 절단 후 부피 보존, 실제 절단 평면과 단면 좌표, 재절단 시 무늬 좌표·반공간 유지, 리소스 해제, 편성·도감·저장 멱등성이다. `npm test`와 `npm run build`를 실행하고 기존 힐링 E2E 및 신규 세 종류의 첫 절단·재절단·수동 다음 이동·재방문을 일반 입력으로 확인한다. 셰이더 컴파일 오류와 WebGL 오류도 검사한다. 프리뷰 서버가 읽는 빌드와 테스트 시점을 일치시킨다.

Android·iOS 빌드나 기기 테스트는 이번 기본 범위에 넣지 않는다. 브라우저의 모바일 해상도 검수를 실기기 외관·성능 검증으로 보고하지 않는다. 배포·main 푸시는 별도 요청 전 수행하지 않는다. 완료 시 `PROGRESS.md`에 구현 내용·시각 검수·실기기 미검증과 실제 검증 결과를 기록한다.

## 사용자 시각 피드백: 투명도 보강 (2026-11-01)

세 종류 모두 조금 더 투명하게 보이도록 외피 투과율을 은하0.82·오팔0.42·비늘0.97로 조정한다. 흡수 거리는2.5, 단면의 상대 투과 배율은0.58로 하여 두꺼운 부분과 단면에서도 빛이 더 통하게 한다. 오팔의 우윳빛 외피, 각 종류의 입체 색상장·반짝이·기포는 유지한다. 이는 신규3종의 재질 수치 조정이며 기존 용과·오로라에는 적용하지 않는다. 같은 두 해상도·상태의 캡처를 전후 비교한다.