# 하단 카드 손패 UI 목업 설계 (Slay the Spire 2 스타일)

- 날짜: 2026-06-06
- 브랜치: feature/sts2-combat-layout
- 대상 파일: `ui/DefaultGroup.ui`

## 목표

전투 화면 **하단에 카드 5장이 수평 일렬로 보이는** 시각 결과를 만든다.
Slay the Spire 2 처럼 손패가 화면 아래쪽에 펼쳐진 느낌을 정적(static) 목업으로 구현한다.

## 범위

### 포함
- `DefaultGroup.ui`에 카드 손패 UI 엔티티 추가
- 카드 5장을 하단 중앙에 수평 일렬 배치
- 각 카드는 "풀 카드 면": 에너지 코스트(좌상단) + 카드 이름(상단 중앙) + 설명(하단)
- 샘플 손패 내용으로 채움 (정적)

### 명시적 제외 (YAGNI)
- 클릭/터치 동작, 에너지 소모, 실제 카드 사용 로직
- `SlayCombatManager` / `SlayCardCatalog` / `SlayRunState` 등 전투 로직 구현
- 부채꼴(fan) 회전·곡선 배치
- 드래그 앤 드롭, 호버 확대, 애니메이션
- 데이터 기반 동적 손패 (드로우/버림에 따른 카드 수 변화)

이들은 이후 "데이터 연동" 단계에서 별도 스펙으로 다룬다.

## 구현 방식

`DefaultGroup.ui`의 `ContentProto.Entities` 배열에 신규 엔티티를 직접 추가한다.
기존 MSW UI 엔티티 패턴(`uisprite`, `uitext`)을 그대로 따르고, 각 엔티티에 새 UUID를 부여한다.

이유:
- 이 프로젝트는 로컬 워크스페이스 + git 방식이므로 `.ui` 파일 직접 편집이 형상관리와 일치
- 결정론적·재현 가능하며 diff로 변경 내역이 명확히 남음
- 작업 후 Maker에서 워크스페이스 reload로 반영

(대안 — Maker MCP 라이브 조작, 런타임 Lua 생성 — 은 재현성/범위 측면에서 부적합하여 제외)

## 엔티티 구조

```
/ui/DefaultGroup/CardHand              컨테이너 (uiempty, 하단 중앙 앵커)
  ├ Card1   (uisprite, 카드 면)
  │   ├ Cost  (uitext, 좌상단 코스트)
  │   ├ Name  (uitext, 상단 중앙 이름)
  │   └ Desc  (uitext, 하단 설명)
  ├ Card2 … Card5  (Card1과 동일한 하위 구조)
```

## 배치 수치

- 좌표 공간: `DefaultGroup` 기준 1920 × 1080 (기존 UITransform과 동일)
- `CardHand` 컨테이너: 하단 중앙 앵커 (AnchorsMin/Max = {0.5, 0}), RectSize 약 1020 × 300, 바닥에서 위로 약 30px 띄움
- 카드 크기: 180 × 250 (폭 × 높이)
- 카드 간격: 20px
- 5장 총폭: `5 × 180 + 4 × 20 = 980px` → CardHand 내부에서 중앙 정렬
- 카드 i의 x 중심 (컨테이너 중앙 기준): `(-2 + i) × 200`  (i = 0..4) → -400, -200, 0, 200, 400

### 카드 내부 텍스트 배치 (카드 로컬 좌표, 180×250 기준)
- Cost: 좌상단, RectSize 약 48×48, 카드 좌상단 모서리 부근
- Name: 상단 중앙, FontSize 약 28
- Desc: 하단, FontSize 약 22

## 비주얼

- 카드 면 배경: 기존 버튼 스프라이트 RUID `cd0560c4fc7f3b14994b90a502f00a21` 재사용
- 카드 타입별 색 틴트 (SpriteGUIRendererComponent.Color):
  - 공격 카드(타격/강타): 붉은톤 (예: r 0.9, g 0.55, b 0.5)
  - 방어 카드(방어): 푸른톤 (예: r 0.55, g 0.7, b 0.95)
- 텍스트 컴포넌트는 기존 `PopupMessage` TextComponent 스키마를 템플릿으로 사용 (FontColor, OutlineColor 등 기본값 유지)

## 샘플 손패 5장

| # | 이름 | 코스트 | 설명     | 타입 틴트 |
|---|------|--------|----------|-----------|
| 1 | 타격 | ①      | 피해 6   | 공격(붉은) |
| 2 | 타격 | ①      | 피해 6   | 공격(붉은) |
| 3 | 방어 | ①      | 방어도 5 | 방어(푸른) |
| 4 | 방어 | ①      | 방어도 5 | 방어(푸른) |
| 5 | 강타 | ②      | 피해 10  | 공격(붉은) |

(StS 시작덱 느낌의 대표 손패. 코스트 표기는 텍스트 "1"/"2"로 입력)

## 검증

1. 파일 저장 후 Maker에서 로컬 워크스페이스 reload
2. `maker_screenshot`으로 전투 화면 하단에 카드 5장이 수평 일렬로 렌더되는지 확인
3. 각 카드에 코스트·이름·설명 텍스트가 보이는지, 공격/방어 색 구분이 되는지 확인

## 후속 단계 (이 스펙 밖)

- 데이터 연동: `SlayCardCatalog` / `SlayCombatManager` 구현 후 손패를 동적 렌더링
- 카드 클릭 → 카드 사용, 에너지 소모, 손패 수 변화
- 부채꼴 배치·호버·드래그 등 인터랙션 고도화