maplecontest/docs/superpowers/specs/2026-06-09-map-camera-design.md

맵별 고정 카메라 (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/전투 로직 변경.