diff --git a/README.md b/README.md index a36437a..fbf36e5 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,10 @@ git pull ``` slaymaple/ ├── data/ # 게임 데이터 단일 소스 (생성기가 읽어 주입) -│ ├── cards.json # 카드 정의 + 시작 덱 -│ ├── enemies.json # 적 정의(슬라임/정예/보스) + activeEnemy -│ ├── map.json # 분기 맵 DAG (노드 type/enemy/row/col/next) -│ └── relics.json # 유물 정의 + 시작 유물 + 풀 +│ ├── cards.json # 카드 32종(클래스·직업별) + 클래스별 시작 덱 +│ ├── enemies.json # 적 정의(일반/정예/보스, 디버프 인텐트 포함) +│ ├── potions.json # 물약 6종 + 드랍률·슬롯·상점가 +│ └── relics.json # 유물 19종(StS 효과 × 메이플 장비) + 시작 유물 + 풀 ├── Global/ # 월드 전역 설정 · 공용 모델 · 게임로직 │ ├── common.gamelogic # SlayDeckController 부착 지점 (카드 UI 전투) │ ├── DefaultPlayer.model # 플레이어 모델 (턴전투용 이동 정지 freeze 적용) @@ -64,15 +64,18 @@ slaymaple/ │ └── map01.map ~ map11.map # 맵 11종 (공식 배경 + STS풍 우측 배치) ├── tools/ # 결정적 생성기·도구 (주체별 폴더, 단일 소스) │ ├── deck/ # gen-slaydeck.mjs(★게임 전체 생성: 카드/덱·맵·상점·유물·메인메뉴 UI+SlayDeckController+common) · gen-cardhand.mjs(손패 초기 생성) -│ ├── map/ # gen-maps.mjs(맵 생성) +│ ├── map/ # gen-maps.mjs(맵 생성) · gen-map-encounters.mjs(맵별 인카운터) · rogue-map.mjs(절차 생성 JS 미러+테스트) │ ├── camera/ # gen-camera.mjs(맵별 고정 카메라 codeblock) │ ├── player/ # freeze-turn-player.mjs(이동 정지) · gen-player-lock.mjs(입력 차단·시선 고정 codeblock) │ ├── monster/ # freeze-turn-monsters.mjs(필드 몬스터 AI/이동 정지) -│ └── balance/ # sim-balance.mjs(밸런스 시뮬·몬테카를로) · sim-balance.test.mjs +│ ├── balance/ # sim-balance.mjs(밸런스 시뮬·몬테카를로) · sim-balance.test.mjs +│ └── git/ # gitea-pr.mjs(UTF-8 안전 PR 생성/수정/머지 — RULES.md 참조) ├── ui/ # UI 그룹 (Default / Popup / Toast) ├── docs/ │ ├── slaymaple_basic_framework.md # 전투 프레임워크 설계 문서 │ └── superpowers/specs|plans/ # 각 기능 설계·구현 계획 문서 +├── RULES.md # 협업·AI 에이전트 하네스 규칙 (토큰 가드·PR 절차) +├── CLAUDE.md # Claude Code 자동 로드 (RULES.md 임포트) └── README.md ``` @@ -82,35 +85,40 @@ slaymaple/ ## 게임 프레임워크 현황 -**STS풍 덱빌더 런이 end-to-end로 완성**됐습니다 — 메인 메뉴 → 분기 맵 → 전투/엘리트/상점/휴식 → 카드 보상·덱 성장 → 유물 → 보스 → 다음 막 → 런 클리어. 게임 전체는 `/common` 엔티티에 부착된 **`SlayDeckController` 단일 컴포넌트**로 동작하며, 모든 산출물(`ui/DefaultGroup.ui` · `SlayDeckController.codeblock` · `common.gamelogic`)은 **`tools/deck/gen-slaydeck.mjs` 단일 소스에서 생성**됩니다(직접 편집 금지, 결정적 출력). 게임 데이터는 **`data/*.json`** 가 단일 소스. +**StS2풍 덱빌더 로그라이크가 end-to-end로 완성**됐습니다 — 메인 메뉴(승천 선택) → 캐릭터 선택(전사/마법사) → 절차 생성 맵 → 전투/엘리트/상점/휴식/유물 방 → 보상·전직·덱 성장 → 보스 → 다음 막 → 런 클리어(승천 해금). 게임 전체는 `/common` 엔티티에 부착된 **`SlayDeckController` 단일 컴포넌트**로 동작하며, 모든 산출물(`ui/DefaultGroup.ui` · `SlayDeckController.codeblock` · `common.gamelogic`)은 **`tools/deck/gen-slaydeck.mjs` 단일 소스에서 생성**됩니다(직접 편집 금지, 결정적 출력 — `RULES.md` 참조). 게임 데이터는 **`data/*.json`** 가 단일 소스. -### 구현된 기능 +### 구현된 기능 (배포 퀄리티 P1~P12, PR #34~#47) | 영역 | 내용 | |---|---| -| **메인 메뉴** | "슬레이 메이플" 타이틀 + "새 게임" → 런 시작 (`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/balance/sim-balance.mjs` — 몬테카를로 N회 전투로 승률·턴·OP 카드 리포트 | -| **턴전투 freeze** | 카드 전투 중 필드 몬스터/플레이어 이동·AI 정지(`freeze-turn-*.mjs`) | +| **캐릭터·전직** | 시작 시 **전사(HP80)/마법사(HP70)** 선택, 클래스별 시작 덱. 보스 클리어 시 [유물] vs [**2차 전직**] — 전사→파이터/페이지/스피어맨, 법사→위자드(불·독)/위자드(썬·콜)/클레릭. 전용 카드는 해당 클래스만 획득(보상·상점 풀 필터) | +| **카드 전투** | 에너지 3·5장 드로우·**드래그 사용**(공격=적에 드롭, 스킬=위로 스윕). 카드 32종 — kind **Attack/Skill/Power**(파워: 소멸·매턴 지속 효과). 메커니즘: 다단히트·방어 무시·자가 디버프·드로·회복·**전체 공격(AoE)**·**독(DoT)** | +| **버프/디버프** | StS 표준 — **힘**(+N 영구)·**약화**(주는 피해 −25%)·**취약**(받는 피해 +50%)·**독**(매 행동 틱). 양방향(적 디버프 인텐트 포함), 인텐트는 최종 예상치 표시 | +| **전투 연출** | 공격 이펙트·데미지 팝업·적 개별 차례·**공격/피격/독뎀 모션**(아바타 상태 전이·몬스터 hit 클립·런지/넉백) | +| **절차 생성 맵** | 막 시작마다 **8층×4열 StS식 경로 생성**(런마다 다름). 층 규칙: 1~2층 전투만 → 3층~ 상점/휴식 → 4층~ 엘리트/**유물 방** → 7층 휴식 가중 → 8층 보스. 점선 경로·상태 4단(현재/방문/도달/잠김)·층 카운터 | +| **유물 방(보물)** | 상자 클릭 → 흔들림 → 열림 연출 → 유물 + 메소 획득 | +| **유물 19종** | StS 효과 × 메이플 장비 외형. TopBar **아이콘 행 + 마우스오버 툴팁**. 훅: combatStart/turnStart/cardPlayed/combatEnd/combatReward/onPlayerDamaged/attackCalc/passive. **장인의 벨트**=물약 슬롯 3→5칸 | +| **물약 6종** | 승리 40% 드랍·상점 판매·슬롯 클릭 → 사용(전투 중)/버리기 메뉴·툴팁 | +| **상점/휴식** | 카드 3종·유물·물약 판매(메소), 휴식=HP 회복 | +| **승천(Ascension)** | A1~A10 누적 모디파이어(적 강화·시작 HP 감소·보상 감소). **UserDataStorage로 유저별 영구 저장**(서버 RPC), 런 클리어 시 다음 단계 해금 | +| **멀티 act** | 보스 클리어→다음 막 텔레포트(맵·인카운터 변경, 적 스케일 `1+(막-1)*0.6`), 3막 클리어 시 런 종료→메뉴 복귀 | +| **밸런스 시뮬** | `tools/balance/sim-balance.mjs` — 전투 규칙 JS 미러(몬테카를로) + `tools/map/rogue-map.mjs`(맵 생성 미러). **테스트 40건** | -> ⚠️ 플레이어 HP(80)·적 수치·골드/카드값(15/30/유물60)·막 배율 등은 **밸런싱 미조정 placeholder**입니다. 추후 카드·적은 **메이플스토리 IP**에 맞춰 디벨롭 예정이며, 밸런싱은 `sim-balance.mjs`로 검증합니다. +> ⚠️ 수치(적 스탯·경제·승천 배율)는 1차 조정 상태입니다. 정밀 밸런싱은 `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:PickReward(1) -- 보상 카드 1택(0=건너뛰기) -c:BuyCard(1) / c:BuyRelic() -- 상점 구매 +c:SelectClass("warrior") -- 또는 "magician" +c:StartNewGame() -- 캐릭터 선택 → 런 시작 +c:PickNode("r1c2") -- 맵 노드 선택 (절차 생성 그리드 id) / "boss" +c:PlayCard(1) -- 손패 slot 카드 사용 +c:EndPlayerTurn() -- 턴 종료 → 적 턴 → 다음 턴 +c:PickReward(1) -- 보상 카드 1택(0=건너뛰기) +c:BuyCard(1) / c:BuyRelic() / c:BuyPotion() -- 상점 구매 +c:SetJob("fighter") -- 전직 (보스 보상 선택 화면에서) +c:AdjustAscension(1) -- 메뉴에서 승천 단계 +1 ``` 밸런스 검증: `node tools/balance/sim-balance.mjs [N] [--seed S]` · 테스트: `node --test tools/balance/sim-balance.test.mjs`. @@ -124,13 +132,17 @@ c:BuyCard(1) / c:BuyRelic() -- 상점 구매 --- -## 다음 구현 단계 (후속 후보) -- [x] 단일 전투 루프 · 데이터 외부화 · 밸런스 시뮬 · 런 루프 · 분기 맵 · 상점/휴식 · 유물 · 멀티 act **(완료)** -- [ ] 저장/불러오기(런 영속 직렬화) — MSW 저장 API 필요 -- [ ] 카드 제거(상점) — 덱 전체 보기 UI 필요 -- [ ] 경제 밸런싱 튜닝(골드/승리 15 < 카드값 30 < 유물 60) — `sim-balance.mjs` 활용 -- [ ] 메이플스토리 IP 기반 카드·적·배경 콘텐츠 확장 -- [ ] 막별 다른 맵 디자인·이벤트 노드 +## 향후 개선 계획 (후속 후보) +- [x] 전투 루프 · 런 루프 · 절차 생성 맵 · 상점/휴식/유물 방 · 유물 19종 · 물약 · 버프/디버프 · Power · 전직(전사/법사 2차) · 승천+개인 저장 · 전투 모션 **(P1~P12 완료)** +- [ ] **런 이어하기** — 진행 중 런 직렬화 저장(승천에서 도입한 UserDataStorage 확장, 메뉴의 "이어하기" 활성화) +- [ ] **카드 제거/업그레이드** — 상점 카드 제거 슬롯, 휴식 노드에서 카드 강화(StS 스타일 +수치) +- [ ] **이벤트 노드(?)** — 랜덤 텍스트 이벤트(선택지·리스크/리워드) +- [ ] **3차 전직** — 2막 보스 보상으로 확장(크루세이더/나이트/버서커, 메이지 3차 등) +- [ ] **도적·궁수 클래스** — 캐릭터 선택 슬롯 확장(도적 잠금 해제), 클래스별 카드 풀 +- [ ] **정밀 밸런싱** — 첫 인카운터 승률 100% 완화, 직업별 카드 효율 튜닝(`sim-balance.mjs` 리포트 기반) +- [ ] **상점 보장 규칙** — 막당 상점 최소 1회 등장(현재 가중 랜덤이라 미등장 가능) +- [ ] **연출 보강** — 사운드(타격·획득), EndTurn 버튼 적 턴 중 시각 비활성화, 맵 화면에 유물/물약 표시 +- [ ] **승천 확장** — A10 초과 단계, 승천별 기록(클리어 횟수) 표시 --- @@ -142,3 +154,4 @@ c:BuyCard(1) / c:BuyRelic() -- 상점 구매 2. MSW Maker에서 이 폴더를 **로컬 워크스페이스 경로**로 지정해 월드 열기 3. `.mcp.json` / `.codex/` 는 git에 없으므로, 본인 토큰으로 직접 생성 (MCP·Codex 사용 시) 4. 작업 전 항상 `git pull`, 작업 후 `git add/commit/push` +5. **AI 에이전트(Claude Code 등)로 작업한다면 [`RULES.md`](RULES.md) 필독** — 생성 산출물 접근 금지(토큰 가드)·검증 절차·PR 도구(`tools/git/gitea-pr.mjs`) 규칙. Claude Code는 `CLAUDE.md`가 자동 적용