# 맵별 고정 카메라 (Map Camera Anchor) — 설계

> 작성: 2026-06-09 / 상태: 승인됨 / 근거: MSW CameraService/CameraComponent API + map01 현재 카메라 런타임 추출.

## 문제

맵별로 카메라 시점을 고정해 타일·배경·몬스터를 결정적 framing 안에 배치하고 싶다. 현재 카메라는
플레이어(DefaultPlayer) 소유로 플레이어를 추적한다(플레이어 freeze로 사실상 고정이지만 플레이어/맵 의존).
맵별로 **명시적·데이터 제어 가능한 고정 시점**이 필요하다.

## 추출한 현재(map01) 카메라 값 (런타임)
- ZoomRatio **100** (min 30 / max 500), CameraOffset (0,0), ScreenOffset **(0.5, 0.655)**,
  ConfineCameraArea **true**, UseCustomBound false.
- 플레이어 스폰 ≈ **(-5.0, -0.04)**, 카메라 가둠 영역 LB(-8.73,-1.76)~RT(7.83,4.35).

## 설계

### 구조
- **맵별 `CameraAnchor` 엔티티**(정적): 각 맵(`/maps/mapNN/CameraAnchor`)에 추가.
  - `TransformComponent`: 위치 = framing 중심(스폰 `(-5, -0.04)`).
  - `CameraComponent`: ZoomRatio 100, ScreenOffset (0.5, 0.655), ConfineCameraArea true (= 현재 값).
  - `script.MapCamera`: 맵 로드 시 이 카메라로 전환.
  - 앵커가 움직이지 않으므로 시점 고정. 플레이어와 분리.
- **`RootDesk/MyDesk/MapCamera.codeblock`**(신규, 1개):
  - `OnBeginPlay`(client): `_CameraService:SwitchCameraTo(self.Entity.CameraComponent)`.
- **`data/camera.json`**(신규): 단일 카메라 설정(zoom·screenOffset·confine·anchor pos). 맵 공통값(맵들이 map01 클론)이며, 추후 맵별 오버라이드 가능 구조.

### 생성기
- `tools/gen-maps.mjs`에 카메라 앵커 주입 추가: `data/camera.json` 읽어 11맵 각각에 CameraAnchor 엔티티
  (Transform+Camera+script.MapCamera) 추가. CameraComponent JSON 구조는 기존 `Global/DefaultPlayer.model`의
  CameraComponent를 복제해 값만 교체(정확한 필드 보존).
- `MapCamera.codeblock`은 `gen-maps.mjs`(또는 별도 소함수)에서 생성. ExecSpace는 클라이언트(OnBeginPlay client).

### 데이터 흐름
`data/camera.json` → `gen-maps.mjs`(앵커 주입) + `MapCamera.codeblock` 생성 → 맵 로드 시
`OnBeginPlay`→`SwitchCameraTo` → 고정 시점. framing 안에 타일/배경/몬스터 배치(기존대로).

### 조정
- 앵커는 메이커 Explorer `/maps/mapNN/CameraAnchor`에 나타나며 Scene에서 카메라 기즈모로 표시·이동 가능.
  값은 Property Editor 또는 `data/camera.json` 수정→재생성으로.

## 검증 (메이커 Play)
- map01 진입 시 카메라가 CameraAnchor로 전환돼 현재와 동일 framing 고정(플레이어 이동/위치 무관).
- (가능하면 map02 진입해 동일 framing 확인.)
- `node tools/gen-maps.mjs` 결정적. 맵 JSON 유효. 빌드 오류 없음.
- 앵커가 Explorer/Scene에 보이고 기즈모로 framing 확인 가능.

## 범위 밖 (금지)
- 맵별 다른 줌/오프셋 튜닝(공통값부터), 카메라 연출(흔들림/줌인/블렌드), 노드별 맵 전환 로직,
  카드 UI/전투 로직 변경.