feat: batch wikification of Skybound balance pass and scalable frontend architectures

Processed 80+ files including Skybound playtest feedback, Monorepo strategies, and Modern Component Patterns.
2026-04-26 13:53:50 +09:00
parent cfafbdbc36
commit f541717fe1
156 changed files with 6543 additions and 243 deletions
@@ -0,0 +1,111 @@
+# Skybound Low Level First Upgrade Offer Balance
+
+작성일: 2026-04-26 13:16 KST
+
+## 요청 요약
+
+- 게임 플레이 중 Tactical Level Up으로 무기/스킬 업그레이드 후보가 나온다.
+- 이미 많이 레벨업한 무기가 계속 후보에 자주 나오면 특정 무기 몰빵이 쉬워진다.
+- 레벨이 낮은 무기/스킬이 다음 후보에 포함될 확률을 더 높인다.
+- 레벨이 높은 무기/스킬은 낮은 레벨 스킬 대비 후보 포함 확률을 낮춘다.
+
+## 핵심 문제
+
+기존 `ProgressionSystem.generateSkillCards()`는 이미 보유한 스킬과 near-max 스킬에 보너스를 주는 구조였다.
+
+기존 구조의 문제:
+
+1. 한 무기가 빠르게 고레벨까지 몰릴 수 있다.
+2. Lv4 → Lv5 직전 스킬이 자주 후보에 떠서 성장 속도가 급격해진다.
+3. 다양한 무기를 경험하기보다 가장 강한 무기 하나가 빠르게 완성된다.
+4. Stage 1-2 중반부터 빌드가 너무 빨리 안정화될 수 있다.
+
+## 적용한 변경
+
+### 후보 선택 방식 변경
+
+기존에는 카테고리별로 후보를 고르고, 보유/시너지/near-max에 가중치를 더했다.
+
+변경 후에는 각 스킬마다 `offer weight`를 계산한다.
+
+가중치 기준:
+
+- 남은 레벨이 많을수록 가중치 증가
+- Lv0/Lv1 스킬은 상대적으로 더 자주 등장
+- Lv3 이상 스킬은 가중치 감소
+- max 직전 스킬은 강하게 가중치 감소
+- 시너지/EVO 보너스는 유지하되, 고레벨 스킬을 압도적으로 밀어주지는 않음
+
+### 고레벨 몰빵 완화
+
+Near-max 스킬은 기존에 오히려 보너스를 받았지만, 이제는 낮은 확률로만 나온다.
+
+적용 규칙:
+
+- `currentLevel >= maxLevel - 1`: 가중치 35%로 감소
+- `currentLevel >= maxLevel * 0.6`: 가중치 58%로 감소
+
+예시:
+
+- Lv0/Lv1 스킬: 목록에 더 잘 등장
+- Lv3/Lv4 스킬: 등장 가능하지만 낮은 빈도
+- Lv4 → Lv5 완성: 운이 좋아야 뜨는 마무리 선택으로 변경
+
+### 첫 선택 보정
+
+아직 아무 스킬도 없는 첫 Tactical Level Up에서는 새 무기 후보를 우선 제공한다.
+
+목표는 첫 선택이 빌드 방향을 정하는 순간으로 작동하게 하는 것이다.
+
+### 새 무기 확장 선택 유지
+
+이미 스킬을 보유한 이후에도 새 무기 후보가 완전히 사라지지는 않는다.
+
+변경 후:
+
+- 슬롯 여유가 있고 새 무기가 있으면 65% 확률로 하나의 build-expanding option을 제공한다.
+- 나머지 후보는 전체 가중치 풀에서 선택한다.
+
+### Mini-boss Reward Cache 보정
+
+미니보스 보상 카드도 가장 높은 레벨 무기를 무조건 우선하지 않도록 변경했다.
+
+변경 후에는 보유 무기 중에서도 낮은 레벨/남은 성장 여지가 큰 무기가 더 잘 선택된다.
+
+### UI fallback 보정
+
+일반적으로 카드 후보는 엔진에서 생성되지만, 예외적으로 `LevelUpModal`에서 fallback 랜덤이 동작할 수 있다.
+
+이 fallback도 동일한 low-level-first 가중치 규칙을 따르도록 변경했다.
+
+## 설계 의도
+
+이번 변경의 목표는 성장 속도를 늦추는 것만이 아니다.
+
+플레이어가 한 무기를 빠르게 완성해 “이미 빌드가 끝났다”라고 느끼는 시점을 뒤로 미루고, 여러 선택지 사이에서 더 오래 고민하게 만드는 것이 핵심이다.
+
+원하는 플레이 감각:
+
+1. 초반에는 새 무기와 낮은 레벨 무기가 자주 보인다.
+2. 중반에는 빌드 방향을 넓히거나 약한 축을 보완하게 된다.
+3. 고레벨 완성 선택은 자주 뜨지 않지만, 떴을 때 반갑다.
+4. 특정 무기 하나가 너무 빨리 완성되어 난이도를 붕괴시키는 일이 줄어든다.
+
+## 수정 파일
+
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.tsx`
+
+## 검증
+
+- `npm run build` 성공
+- `/sprites/player.png` 경고 없음
+- 출력 디렉터리: `dist/26`
+
+## 후속 플레이테스트 체크 포인트
+
+- Stage 1에서 같은 무기가 너무 빠르게 Lv4/Lv5까지 올라가지 않는지 확인한다.
+- 낮은 레벨 무기/패시브가 기존보다 자주 후보에 뜨는지 확인한다.
+- 고레벨 완성 선택이 너무 안 떠서 답답하지 않은지 확인한다.
+- EVO 경로가 완전히 막힌 느낌이 들지 않는지 확인한다.
+- 미니보스 보상 카드가 여전히 보상답게 느껴지는지 확인한다.
@@ -0,0 +1,136 @@
+# Skybound Skill Slot Limit Weapon 5 Passive 5
+
+작성일: 2026-04-26 13:29 KST
+
+## 요청 요약
+
+- 사용자가 획득할 수 있는 스킬 수량에 제한을 둔다.
+- 총 10개 스킬을 보유할 수 있게 한다.
+- 10개 중 5개는 무기, 5개는 패시브로 분리한다.
+- 슬롯이 부족한 상태에서 새 스킬을 선택하려 하면 `슬롯이 부족합니다`에 해당하는 노티가 필요하다.
+- 슬롯 제한 때문에 사용하지 못하는 스킬이 목록에 나올 수 있으므로 `Skip Upgrade` 선택지도 계속 필요하다.
+- 5/5 구조가 적절한지 검토한다.
+
+## 판단
+
+현재 Skybound에는 무기와 패시브 풀이 이미 넓고, 8스테이지까지 성장해야 한다.
+
+따라서 지금 시점에서는 `무기 5개 + 패시브 5개`가 적절하다.
+
+더 줄이는 선택지도 가능하지만, 아직은 권장하지 않는다.
+
+- 4/4는 빌드 정체성이 더 강해지는 대신 초반 선택 운 영향이 커진다.
+- 5/5는 Survivor.io/Vampire Survivors류의 성장 폭과 전략성을 적당히 유지한다.
+- 6/6 이상은 사용자가 거의 모든 것을 들고 가는 느낌이 강해져 빌드 선택 의미가 약해진다.
+
+그래서 이번 패스에서는 5/5를 기본값으로 적용했다.
+
+## 적용한 변경
+
+### Skill Slot Limit 추가
+
+`skills.ts`에 슬롯 제한 상수를 추가했다.
+
+```ts
+export const SKILL_SLOT_LIMITS = {
+  WEAPON: 5,
+  PASSIVE: 5,
+}
+```
+
+이제 시스템 전반에서 동일한 기준을 사용한다.
+
+### 후보 생성 필터링
+
+`ProgressionSystem.generateSkillCards()`와 `generateMiniBossRewardCards()`에서 슬롯 제한을 반영했다.
+
+규칙:
+
+- 이미 보유한 스킬은 계속 레벨업 가능하다.
+- 새 무기 획득은 무기 슬롯이 5개 미만일 때만 가능하다.
+- 새 패시브 획득은 패시브 슬롯이 5개 미만일 때만 가능하다.
+- 슬롯이 꽉 찬 타입의 새 스킬은 정상 후보 생성에서 제외한다.
+
+### 선택 시 슬롯 부족 방어
+
+혹시 예외 경로로 선택 불가 카드가 들어오거나, UI/엔진 동기화 타이밍 문제로 새 스킬 선택이 들어올 수 있다.
+
+그래서 `ProgressionSystem.applySkillSelection()`에도 최종 방어를 추가했다.
+
+슬롯이 부족하면:
+
+- 스킬을 추가하지 않는다.
+- 게임을 재개한다.
+- 전투 화면에 `WEAPON SLOTS FULL` 또는 `PASSIVE SLOTS FULL` 텍스트를 띄운다.
+- 보조 텍스트로 `Choose another module or skip`을 띄운다.
+
+### Store 레벨 방어
+
+`useGameStore.addSkill()`에도 동일한 슬롯 제한 방어를 추가했다.
+
+이유:
+
+- UI나 엔진 외부에서 `addSkill()`이 호출되더라도 잘못된 스킬이 저장되지 않게 하기 위함이다.
+- `__skip__`도 기존처럼 저장되지 않는다.
+
+### Level Up UI 슬롯 상태 표시
+
+`LevelUpModal` 상단에 현재 슬롯 상태를 표시한다.
+
+표시:
+
+- `Weapons 0/5`
+- `Passives 0/5`
+
+슬롯이 가득 차면 해당 배지가 붉은 톤으로 바뀐다.
+
+### SLOT FULL 카드 표시
+
+정상 후보 생성에서는 사용 불가 카드가 거의 나오지 않지만, 예외적으로 pre-generated cards나 fallback 상태에서 들어올 수 있다.
+
+이 경우 카드에 다음 표시를 추가했다.
+
+- `SLOT FULL` 태그
+- `No empty weapon/passive slot` 설명
+- `WEAPON slots are full` 또는 `PASSIVE slots are full`
+
+사용자는 이때 새로 추가된 `Skip Upgrade`를 선택해 넘길 수 있다.
+
+## 설계 의도
+
+슬롯 제한의 핵심은 빌드 선택을 더 전략적으로 만드는 것이다.
+
+제한이 없으면 사용자는 결국 대부분의 무기와 패시브를 다 들고 가게 되고, 선택의 의미가 약해진다.
+
+5/5 구조에서는 다음 판단이 생긴다.
+
+1. 무기 슬롯 하나를 새 무기에 쓸 것인가?
+2. 기존 무기 레벨업을 기다릴 것인가?
+3. 패시브 슬롯을 EVO 재료에 쓸 것인가?
+4. 생존 패시브를 포기하고 공격 패시브를 가져갈 것인가?
+5. 지금 후보가 별로면 스킵할 것인가?
+
+이번 변경은 `Skip Upgrade`의 존재 이유도 더 명확하게 만든다.
+
+## 수정 파일
+
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/skills.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/store/useGameStore.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.tsx`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.css`
+
+## 검증
+
+- `npm run build` 성공
+- `/sprites/player.png` 경고 없음
+- 출력 디렉터리: `dist/28`
+
+## 후속 플레이테스트 체크 포인트
+
+- 무기 5개를 보유한 상태에서 새 무기 후보가 정상 레벨업 목록에서 제외되는지 확인한다.
+- 패시브 5개를 보유한 상태에서 새 패시브 후보가 정상 레벨업 목록에서 제외되는지 확인한다.
+- 이미 보유한 무기/패시브는 슬롯이 가득 차도 레벨업 가능한지 확인한다.
+- 예외적으로 `SLOT FULL` 카드가 보일 때 선택하면 슬롯 부족 노티가 뜨는지 확인한다.
+- `Skip Upgrade`가 슬롯 제한 상황에서 자연스러운 탈출구로 작동하는지 확인한다.
+- 5/5가 너무 넉넉하거나 너무 답답하지 않은지 확인한다.
@@ -0,0 +1,150 @@
+# Skybound Skip Upgrade and Weapon Transform Reconfiguration
+
+작성일: 2026-04-26 13:25 KST
+
+## 요청 요약
+
+- Tactical Level Up 화면에서 마음에 들지 않는 업그레이드만 나올 수 있다.
+- 이 경우 사용자가 강제로 원하지 않는 업그레이드를 고르지 않도록 `업글 안하기` 선택지를 추가한다.
+- 새로운 무기가 장착되었을 때 사용자의 기체 외형도 그에 맞춰 변화해야 한다.
+- 연출적으로는 트랜스포머처럼 기체가 재구성되고 무장이 전개되는 느낌을 표현한다.
+
+## 핵심 문제
+
+기존 레벨업 화면은 반드시 하나의 스킬을 선택해야 했다.
+
+이 구조의 문제:
+
+1. 현재 빌드와 맞지 않는 선택지만 나와도 강제로 선택해야 한다.
+2. 낮은 레벨 우선 후보 확률을 적용한 뒤에는 사용자가 원치 않는 저레벨/새 무기가 뜰 가능성도 생긴다.
+3. 새 무기를 획득해도 기체가 실제로 바뀌는 느낌이 약하다.
+4. 무기가 생긴 순간의 시각적 보상이 부족하다.
+
+## 적용한 변경
+
+### Skip Upgrade 선택지 추가
+
+`LevelUpModal`에 `Skip Upgrade` 카드를 추가했다.
+
+동작:
+
+- STARTER 첫 무기 선택에서는 스킵이 나오지 않는다.
+- 일반 Tactical Upgrade, Supply, Command Cache에서는 스킵 가능하다.
+- 스킵을 선택하면 스킬/무기 레벨이 증가하지 않고 전투로 복귀한다.
+
+표시 문구:
+
+- `HOLD UPGRADE`
+- `Skip Upgrade`
+- `No change this time`
+
+### Skip 안전 처리
+
+`__skip__`이 실제 스킬처럼 저장되지 않도록 여러 지점에 방어를 추가했다.
+
+적용 지점:
+
+- `GameSceneRenderer`
+- `ProgressionSystem`
+- `useGameStore.addSkill`
+
+`__skip__`이 선택되면:
+
+- Zustand `skills`에 추가하지 않는다.
+- 엔진 스킬 상태에도 추가하지 않는다.
+- `TACTICAL UPGRADE HELD` 텍스트를 띄운다.
+- 게임 pause를 해제하고 전투를 재개한다.
+
+### 새 무기 장착 감지
+
+`ProgressionSystem.applySkillSelection()`에서 선택 직전 스킬 레벨을 확인한다.
+
+조건:
+
+- 선택한 스킬이 `WEAPON` 타입
+- 선택 직전 레벨이 0
+
+이 조건을 만족할 때만 새 무기 장착 연출을 발동한다.
+
+기존 무기 레벨업이나 패시브 선택은 변신 연출을 발동하지 않는다.
+
+### Airframe Reconfiguration 상태 추가
+
+`GameState`에 새 무기 장착 연출용 상태를 추가했다.
+
+추가 필드:
+
+- `weaponTransformStartFrame`
+- `weaponTransformDuration`
+- `weaponTransformSkillId`
+
+이 값은 렌더러가 현재 프레임 기준으로 변신 진행도를 계산하는 데 사용한다.
+
+### 기체 변신/무장 전개 연출 추가
+
+`GameRenderer.renderPlayer()`에 새 무기 장착 연출을 추가했다.
+
+연출 요소:
+
+- 기체 중심에서 확장되는 아케인 스캔 링
+- 무기 색상별 발광
+- 좌우 장갑 패널이 바깥으로 접히듯 전개
+- 전방 무장 레일이 앞으로 돌출
+- 작은 locking spark
+- `WEAPON LINK: 무기명`
+- `AIRFRAME RECONFIGURING`
+- 화면 흔들림과 파티클
+
+무기별 액센트 컬러:
+
+- Gatling Gun: 골드
+- Missile Pod: 핑크/레드
+- Nova Burst: 시안
+- Energy Shield: 라임
+- Sweep Laser: 화이트/시안
+- Plasma Torpedo: 오렌지
+- Ion Storm: 전기 시안
+- Attack Drone: 라임
+- Gravity Mine: 퍼플
+- Plasma Fire: 오렌지/레드
+- Plasma Blade: 시안
+
+## 설계 의도
+
+이번 변경은 업그레이드 UX에 “선택하지 않을 권리”를 추가하는 작업이다.
+
+업그레이드는 항상 이득처럼 보여야 하지만, 빌드 방향과 맞지 않는 선택을 강제하면 사용자는 선택권을 잃었다고 느낄 수 있다.
+
+스킵 선택지는 다음 의미를 가진다.
+
+1. 원하지 않는 업그레이드를 강제로 먹지 않는다.
+2. 빌드 순도를 유지할 수 있다.
+3. 낮은 레벨 우선 후보 시스템의 부작용을 완화한다.
+4. 선택 화면에서 사용자 판단 여지를 높인다.
+
+새 무기 변신 연출은 “새 기능이 생겼다”를 UI 문구가 아니라 기체 자체 변화로 전달하기 위한 장치다.
+
+## 수정 파일
+
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/store/useGameStore.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/ProgressionSystem.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/GameRenderer.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/systems/types.ts`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/GameSceneRenderer.tsx`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.tsx`
+- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/LevelUpModal.css`
+
+## 검증
+
+- `npm run build` 성공
+- `/sprites/player.png` 경고 없음
+- 출력 디렉터리: `dist/27`
+
+## 후속 플레이테스트 체크 포인트
+
+- 일반 레벨업 화면에서 `Skip Upgrade`가 명확하게 보이는지 확인한다.
+- STARTER 첫 무기 선택에서는 스킵이 나오지 않는지 확인한다.
+- 스킵 선택 시 게임이 정상 재개되는지 확인한다.
+- 스킵 선택 후 `skills.__skip__` 같은 잘못된 값이 저장되지 않는지 확인한다.
+- 새 무기를 처음 선택했을 때 기체 변신 연출이 충분히 눈에 띄는지 확인한다.
+- 기존 무기 레벨업/패시브 선택 시 변신 연출이 과하게 반복되지 않는지 확인한다.