SlayMaple

MapleStory Worlds(MSW) 기반으로 제작하는 Slay the Spire 풍 덱빌더 로그라이크 월드. 턴제 카드 전투, 덱 구성, 보상 선택, 맵 노드 진행을 메이플 월드 위에서 구현하는 것을 목표로 합니다.

이 저장소는 MSW 로컬 워크스페이스(Local Workspace) 데이터를 git으로 형상관리하기 위한 것입니다. 공동작업자는 이 저장소를 통해 월드 데이터를 주고받습니다. (클라우드 공동제작 모드 미사용)

---

협업 방식 (중요)

MSW에는 두 가지 공동작업 모드가 있고, 이 프로젝트는 로컬 워크스페이스 + git 방식을 사용합니다.

	클라우드 공동제작	로컬 워크스페이스 + git (이 프로젝트)
데이터 위치	넥슨 클라우드 단일 월드	각자 PC 로컬 + git 원격
공유 단위	Check In / Check Out	git commit / push / pull
충돌 처리	엔티티 잠금	git merge

⚠️ 로컬 워크스페이스를 켜면 메이커 내 실시간 동기화(클라우드 공동제작)는 비활성화됩니다. 따라서 변경 공유는 전적으로 git을 통해 이루어집니다.

내 작업을 공유하기

git add .
git commit -m "작업 내용"
git push

공동작업자 작업 받아오기

git pull

받아온 뒤, 메이커에서 로컬 워크스페이스를 다시 로드(reload) 해야 새 codeblock/모델 파일이 에디터 상태로 반영됩니다.

💡 같은 파일을 동시에 수정하면 git 충돌이 날 수 있으니, 서로 다른 맵/codeblock/UI를 나눠서 작업하는 것을 권장합니다.

---

디렉토리 구조

slaymaple/
├── Global/                     # 월드 전역 설정 · 공용 모델 · 게임로직
│   ├── common.gamelogic        # SlayDeckController 부착 지점 (카드 UI 전투)
│   ├── Player.model            # 플레이어 모델
│   ├── *.model                 # 몬스터 등 공용 모델
│   ├── WorldConfig.config      # 월드 설정
│   └── ...
├── RootDesk/
│   └── MyDesk/                 # 작업용 책상 — codeblock(스크립트)·모델·타일셋
│       ├── SlayDeckController.codeblock  # 카드 UI 전투 컨트롤러 (생성물)
│       ├── Monster.codeblock      # 필드 액션 몬스터 (HP·피격·리스폰, 카드 전투와 별개)
│       ├── 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             # 맵 생성
├── ui/                         # UI 그룹 (Default / Popup / Toast)
├── docs/
│   └── slaymaple_basic_framework.md   # 전투 프레임워크 설계 문서
└── README.md

.mcp.json, .codex/ 는 Authorization 토큰이 포함되어 있어 git에서 제외됩니다(.gitignore). 각자 로컬에서 직접 구성하세요.

---

게임 프레임워크 현황

현재 전투는 Global/common.gamelogic의 /common 엔티티에 부착된 SlayDeckController 단일 컴포넌트로 동작합니다. 모든 카드/덱/전투 관련 산출물(ui/DefaultGroup.ui · RootDesk/MyDesk/SlayDeckController.codeblock · common.gamelogic)은 tools/gen-slaydeck.mjs 단일 소스에서 생성됩니다(직접 편집 금지, 결정적 출력).

컴포넌트	상태	역할
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·방어)·승패 결과 텍스트.

⚠️ 플레이어 HP(80)·적 HP(45)·의도 수치(10·6·8)는 루프 검증용 임시 placeholder입니다. 향후 캐릭터 특성별/몬스터별 데이터로 분리할 예정입니다(아래 D 참조).

유용한 스크립트 호출

/common 엔티티(또는 Play Test 컨텍스트)에서:

local c = _EntityService:GetEntityByPath("/common").SlayDeckController
c:PlayCard(1)        -- 손패 slot 카드 사용
c:EndPlayerTurn()    -- 턴 종료 → 적 턴 → 다음 턴
c:StartCombat()      -- 전투 재시작(상태 초기화)

상세 설계는 docs/slaymaple_basic_framework.md 참조.

---

향후 설계 (미구현 — 목표 아키텍처)

아래는 로그라이크 메타까지 확장했을 때의 목표 컴포넌트 구조로, 현재는 미구현입니다. (현재는 SlayDeckController 하나가 카드 전투만 담당)

컴포넌트 (계획)	역할
SlayCardCatalog	카드 데이터, 시작 덱 구성, 보상 풀, 카드 복제 정의
SlayRunState	HP·골드·층수·덱·유물·카드 보상 등 런(run) 영속 데이터 관리
SlayCombatManager	턴 진행, 드로우/버림/소멸 더미, 에너지, 적 의도, 방어도, 데미지, 승패 처리

위 구조로 가더라도 카드/적 데이터는 tools/의 결정적 생성기를 단일 소스로 유지하는 방향을 권장합니다.

---

다음 구현 단계

• HP·방어도·에너지·적 의도·손패 카드를 렌더링하는 전투 UI (완료 — SlayDeckController + CombatHud)
• 카드 사용이 실제 데미지/방어/적 의도/승패에 반영되는 단일 전투 루프 (완료)
• 카드/적 데이터를 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 후)

---

신규 참여자 셋업

1. 저장소 클론

   git clone https://gitea.gahusb.synology.me/gahusb/maplecontest.git slaymaple
   

2. MSW Maker에서 이 폴더를 로컬 워크스페이스 경로로 지정해 월드 열기
3. .mcp.json / .codex/ 는 git에 없으므로, 본인 토큰으로 직접 생성 (MCP·Codex 사용 시)
4. 작업 전 항상 git pull, 작업 후 git add/commit/push