From f310d2978eec1bccdbea8831c421ce8d88b17bdd Mon Sep 17 00:00:00 2001 From: gahusb Date: Tue, 9 Jun 2026 13:51:20 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20README=EB=A5=BC=20=EC=A0=84=EC=B2=B4=20?= =?UTF-8?q?=EA=B5=AC=ED=98=84(B~E6a+=EB=A9=94=EC=9D=B8=EB=A9=94=EB=89=B4+f?= =?UTF-8?q?reeze)=EC=97=90=20=EB=A7=9E=EA=B2=8C=20=EA=B0=B1=EC=8B=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 디렉토리 구조(data/·tools 도구), 게임 프레임워크 현황(메인메뉴·카드전투·런영속·보상·분기맵·상점/휴식·유물·멀티act·밸런스시뮬·freeze), 스크립트 호출, 다음 단계(저장·카드제거·밸런싱·IP확장) 반영. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 100 +++++++++++++++++++++++++++--------------------------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 80fa45e..ea14446 100644 --- a/README.md +++ b/README.md @@ -42,31 +42,37 @@ git pull ``` slaymaple/ +├── data/ # 게임 데이터 단일 소스 (생성기가 읽어 주입) +│ ├── cards.json # 카드 정의 + 시작 덱 +│ ├── enemies.json # 적 정의(슬라임/정예/보스) + activeEnemy +│ ├── map.json # 분기 맵 DAG (노드 type/enemy/row/col/next) +│ └── relics.json # 유물 정의 + 시작 유물 + 풀 ├── Global/ # 월드 전역 설정 · 공용 모델 · 게임로직 │ ├── common.gamelogic # SlayDeckController 부착 지점 (카드 UI 전투) -│ ├── Player.model # 플레이어 모델 -│ ├── *.model # 몬스터 등 공용 모델 +│ ├── DefaultPlayer.model # 플레이어 모델 (턴전투용 이동 정지 freeze 적용) +│ ├── *.model # 몬스터 등 공용 모델 (freeze 적용) │ ├── WorldConfig.config # 월드 설정 │ └── ... ├── RootDesk/ │ └── MyDesk/ # 작업용 책상 — codeblock(스크립트)·모델·타일셋 -│ ├── SlayDeckController.codeblock # 카드 UI 전투 컨트롤러 (생성물) +│ ├── SlayDeckController.codeblock # 게임 전체 컨트롤러 (생성물, 직접 편집 금지) │ ├── Monster.codeblock # 필드 액션 몬스터 (HP·피격·리스폰, 카드 전투와 별개) -│ ├── MonsterAttack.codeblock -│ ├── PlayerAttack.codeblock -│ ├── PlayerHit.codeblock -│ ├── UIPopup.codeblock -│ ├── UIToast.codeblock +│ ├── MonsterAttack.codeblock · PlayerAttack.codeblock · PlayerHit.codeblock +│ ├── UIPopup.codeblock · UIToast.codeblock │ └── RectTileData_Henesys.tileset ├── map/ -│ ├── map01.map ~ map11.map # 맵 11종 (공식 배경 + STS풍 우측 배치) -├── tools/ # 결정적 생성기 (단일 소스) -│ ├── gen-slaydeck.mjs # 카드/덱 UI · SlayDeckController · common 생성 -│ ├── gen-cardhand.mjs # 손패 카드 엔티티 생성 -│ └── gen-maps.mjs # 맵 생성 +│ └── map01.map ~ map11.map # 맵 11종 (공식 배경 + STS풍 우측 배치) +├── tools/ # 결정적 생성기·도구 (단일 소스) +│ ├── gen-slaydeck.mjs # ★ 게임 전체 생성: 카드/덱·맵·상점·유물·메인메뉴 UI + SlayDeckController + common +│ ├── gen-cardhand.mjs # 손패 카드 엔티티 초기 생성 +│ ├── gen-maps.mjs # 맵 생성 +│ ├── sim-balance.mjs # AI 전투 밸런스 시뮬레이터(몬테카를로) + sim-balance.test.mjs +│ ├── freeze-turn-monsters.mjs # 턴전투용 필드 몬스터 AI/이동 정지 패치 +│ └── freeze-turn-player.mjs # 턴전투용 플레이어 이동 정지 패치 ├── ui/ # UI 그룹 (Default / Popup / Toast) ├── docs/ -│ └── slaymaple_basic_framework.md # 전투 프레임워크 설계 문서 +│ ├── slaymaple_basic_framework.md # 전투 프레임워크 설계 문서 +│ └── superpowers/specs|plans/ # 각 기능 설계·구현 계획 문서 └── README.md ``` @@ -76,61 +82,55 @@ slaymaple/ ## 게임 프레임워크 현황 -현재 전투는 `Global/common.gamelogic`의 `/common` 엔티티에 부착된 **`SlayDeckController` 단일 컴포넌트**로 동작합니다. 모든 카드/덱/전투 관련 산출물(`ui/DefaultGroup.ui` · `RootDesk/MyDesk/SlayDeckController.codeblock` · `common.gamelogic`)은 **`tools/gen-slaydeck.mjs` 단일 소스에서 생성**됩니다(직접 편집 금지, 결정적 출력). +**STS풍 덱빌더 런이 end-to-end로 완성**됐습니다 — 메인 메뉴 → 분기 맵 → 전투/엘리트/상점/휴식 → 카드 보상·덱 성장 → 유물 → 보스 → 다음 막 → 런 클리어. 게임 전체는 `/common` 엔티티에 부착된 **`SlayDeckController` 단일 컴포넌트**로 동작하며, 모든 산출물(`ui/DefaultGroup.ui` · `SlayDeckController.codeblock` · `common.gamelogic`)은 **`tools/gen-slaydeck.mjs` 단일 소스에서 생성**됩니다(직접 편집 금지, 결정적 출력). 게임 데이터는 **`data/*.json`** 가 단일 소스. -| 컴포넌트 | 상태 | 역할 | -|---|---|---| -| `SlayDeckController` | ✅ 구현됨 | 카드 손패 UI 전투 — 드로우/버림/재셔플, 에너지, 카드 효과(데미지/방어), 적 HP·방어·의도, 턴 진행, 승패 | -| `Monster.codeblock` | ✅ 구현됨 | 필드 액션 몬스터(HP·피격·리스폰) — 카드 전투와는 **별개** 시스템 | +### 구현된 기능 -### 구현된 카드 전투 (단일 전투 루프) -- **카드 손패 UI**: 에너지 3, 매 턴 5장 드로우, 버림 더미·재셔플, 카드 클릭 사용, 종류별 색상. -- **카드 3종**: 타격(피해 6) · 방어(방어도 5) · 강타(피해 10). 각 카드에 `damage`/`block` 수치 필드. 시작 덱 10장. -- **전투 상태**: 플레이어 `HP`/`Block`, 적 `HP`/`Block`/`Intent(의도)`. 적 의도는 **결정적 사이클**(공격10 → 공격6 → 방어8)로 다음 행동을 미리 표시. -- **규칙**: 데미지는 방어도 먼저 차감 후 잔여만 HP에 적용. 플레이어 Block은 턴 시작 시 리셋. -- **턴 흐름**: 카드 사용(`Attack`→적 HP↓, `Skill`→플레이어 Block↑) → 턴 종료 → 적 턴(의도 실행) → 다음 플레이어 턴. -- **승패**: 적 HP 0 → 승리, 플레이어 HP 0 → 패배. 승패 시 입력 잠금 + 결과 표시(전투 보상 훅 자리 = E 예정). -- **UI(CombatHud)**: 적 패널(이름·HP·방어·의도)·플레이어 패널(HP·방어)·승패 결과 텍스트. +| 영역 | 내용 | +|---|---| +| **메인 메뉴** | "슬레이 메이플" 타이틀 + "새 게임" → 런 시작 (`OnBeginPlay`→`ShowMainMenu`) | +| **카드 전투** | 에너지 3·매 턴 5장 드로우·버림/재셔플·카드 클릭 사용. 카드 3종(타격/방어/강타, `damage`/`block` 수치). 적 HP/방어/의도(결정적 사이클·다음 행동 미리 표시). 데미지는 방어 우선 차감. 승/패·입력 잠금 | +| **런 영속** | HP·골드·`RunDeck`(보유 카드)가 전투 간 유지. 시작 덱 10장 | +| **전투 보상** | 승리 시 카드 3중 1택(덱 추가)·골드, 또는 건너뛰기 | +| **분기 맵** | 작성된 DAG(`data/map.json`)에서 다음 노드 선택. 노드 타입 전투/엘리트/보스(적 데이터 차등), 상점/휴식. 도달 가능 노드만 선택 | +| **상점/휴식** | 상점=골드로 카드·유물 구매. 휴식=HP 회복 | +| **유물** | 훅 패시브(`combatStart`/`turnStart`/`cardPlayed`/`combatReward`). 획득 3경로(시작·엘리트 승리·상점). 유물 4종 | +| **멀티 act** | 보스 클리어→다음 막(적 스케일 `1+(막-1)*0.6`), 최종 막 보스에서 런 클리어. 막 수 3 | +| **밸런스 시뮬** | `tools/sim-balance.mjs` — 몬테카를로 N회 전투로 승률·턴·OP 카드 리포트 | +| **턴전투 freeze** | 카드 전투 중 필드 몬스터/플레이어 이동·AI 정지(`freeze-turn-*.mjs`) | -> ⚠️ 플레이어 HP(80)·적 HP(45)·의도 수치(10·6·8)는 **루프 검증용 임시 placeholder**입니다. -> 향후 캐릭터 특성별/몬스터별 데이터로 분리할 예정입니다(아래 D 참조). +> ⚠️ 플레이어 HP(80)·적 수치·골드/카드값(15/30/유물60)·막 배율 등은 **밸런싱 미조정 placeholder**입니다. 추후 카드·적은 **메이플스토리 IP**에 맞춰 디벨롭 예정이며, 밸런싱은 `sim-balance.mjs`로 검증합니다. ### 유용한 스크립트 호출 `/common` 엔티티(또는 Play Test 컨텍스트)에서: ```lua local c = _EntityService:GetEntityByPath("/common").SlayDeckController +c:StartNewGame() -- 메뉴 → 런 시작 +c:PickNode("A") -- 맵 노드 선택 → 전투/상점/휴식 c:PlayCard(1) -- 손패 slot 카드 사용 c:EndPlayerTurn() -- 턴 종료 → 적 턴 → 다음 턴 -c:StartCombat() -- 전투 재시작(상태 초기화) +c:PickReward(1) -- 보상 카드 1택(0=건너뛰기) +c:BuyCard(1) / c:BuyRelic() -- 상점 구매 ``` -상세 설계는 [`docs/slaymaple_basic_framework.md`](docs/slaymaple_basic_framework.md) 참조. +밸런스 검증: `node tools/sim-balance.mjs [N] [--seed S]` · 테스트: `node --test tools/sim-balance.test.mjs`. +상세 설계는 [`docs/slaymaple_basic_framework.md`](docs/slaymaple_basic_framework.md) 및 `docs/superpowers/specs/` 참조. --- -## 향후 설계 (미구현 — 목표 아키텍처) +## 아키텍처 메모 -아래는 로그라이크 메타까지 확장했을 때의 **목표 컴포넌트 구조**로, 현재는 미구현입니다. (현재는 `SlayDeckController` 하나가 카드 전투만 담당) - -| 컴포넌트 (계획) | 역할 | -|---|---| -| `SlayCardCatalog` | 카드 데이터, 시작 덱 구성, 보상 풀, 카드 복제 정의 | -| `SlayRunState` | HP·골드·층수·덱·유물·카드 보상 등 런(run) 영속 데이터 관리 | -| `SlayCombatManager` | 턴 진행, 드로우/버림/소멸 더미, 에너지, 적 의도, 방어도, 데미지, 승패 처리 | - -> 위 구조로 가더라도 카드/적 데이터는 `tools/`의 결정적 생성기를 단일 소스로 유지하는 방향을 권장합니다. +현재 게임 전체 로직이 `SlayDeckController` 단일 codeblock에 모여 있습니다. 초기 설계 문서가 제안한 3분할(`SlayCardCatalog`/`SlayRunState`/`SlayCombatManager`)은 **기능적으로 모두 구현**됐으나 아직 한 컴포넌트 안에 있습니다. 시스템이 더 커지면 그때 분리를 고려합니다. 카드/적/맵/유물 데이터는 이미 `data/*.json`로 외부화돼 있습니다. --- -## 다음 구현 단계 -- [x] HP·방어도·에너지·적 의도·손패 카드를 렌더링하는 전투 UI **(완료 — `SlayDeckController` + CombatHud)** -- [x] 카드 사용이 실제 데미지/방어/적 의도/승패에 반영되는 단일 전투 루프 **(완료)** -- [ ] 카드/적 데이터를 `data/cards.json` · `data/enemies.json`로 외부화 (D) -- [ ] 전투를 N회 자동 시뮬레이션하는 밸런스 검증 도구 `tools/sim-balance.mjs` (F, D 선행) -- [ ] 전투/엘리트/상점/휴식/이벤트/보스 노드를 가진 맵 노드 UI (E) -- [ ] `OnCombatStart` / `OnCardPlayed` / `OnTurnStart` / `OnCombatReward` 훅을 가진 유물 시스템 (E) -- [ ] 적 행동 패턴을 데이터로 정의 (현재 단순 결정적 의도 사이클 → 무브셋) -- [ ] 런 영속(HP/골드/층/덱/유물) + 저장/불러오기 (E, 루프 end-to-end 후) +## 다음 구현 단계 (후속 후보) +- [x] 단일 전투 루프 · 데이터 외부화 · 밸런스 시뮬 · 런 루프 · 분기 맵 · 상점/휴식 · 유물 · 멀티 act **(완료)** +- [ ] 저장/불러오기(런 영속 직렬화) — MSW 저장 API 필요 +- [ ] 카드 제거(상점) — 덱 전체 보기 UI 필요 +- [ ] 경제 밸런싱 튜닝(골드/승리 15 < 카드값 30 < 유물 60) — `sim-balance.mjs` 활용 +- [ ] 메이플스토리 IP 기반 카드·적·배경 콘텐츠 확장 +- [ ] 막별 다른 맵 디자인·이벤트 노드 ---