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/
├── data/                       # 게임 데이터 단일 소스 (생성기가 읽어 주입)
│   ├── cards.json              # 카드 32종(클래스·직업별) + 클래스별 시작 덱
│   ├── enemies.json            # 적 정의(일반/정예/보스, 디버프 인텐트 포함)
│   ├── potions.json            # 물약 6종 + 드랍률·슬롯·상점가
│   └── relics.json             # 유물 19종(StS 효과 × 메이플 장비) + 시작 유물 + 풀
├── Global/                     # 월드 전역 설정 · 공용 모델 · 게임로직
│   ├── common.gamelogic        # SlayDeckController 부착 지점 (카드 UI 전투)
│   ├── DefaultPlayer.model     # 플레이어 모델 (턴전투용 이동 정지 freeze 적용)
│   ├── *.model                 # 몬스터 등 공용 모델 (freeze 적용)
│   ├── WorldConfig.config      # 월드 설정
│   └── ...
├── RootDesk/
│   └── MyDesk/                 # 작업용 책상 — codeblock(스크립트)·모델·타일셋
│       ├── SlayDeckController.codeblock  # 게임 전체 컨트롤러 (생성물, 직접 편집 금지)
│       ├── Monster.codeblock      # 필드 액션 몬스터 (HP·피격·리스폰, 카드 전투와 별개)
│       ├── MonsterAttack.codeblock · PlayerAttack.codeblock · PlayerHit.codeblock
│       ├── UIPopup.codeblock · UIToast.codeblock
│       └── RectTileData_Henesys.tileset
├── map/
│   └── map01.map ~ map11.map    # 맵 11종 (공식 배경 + STS풍 우측 배치)
├── tools/                       # 결정적 생성기·도구 (주체별 폴더, 단일 소스)
│   ├── deck/                    # gen-slaydeck.mjs(★게임 전체 생성: 카드/덱·맵·상점·유물·메인메뉴 UI+SlayDeckController+common) · gen-cardhand.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
│   └── 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

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

---

게임 프레임워크 현황

StS2풍 덱빌더 로그라이크가 end-to-end로 완성됐습니다 — 메인 메뉴(승천 선택) → 캐릭터 선택(전사/마법사) → 절차 생성 맵 → 전투/엘리트/상점/휴식/유물 방 → 보상·전직·덱 성장 → 보스 → 다음 막 → 런 클리어(승천 해금). 게임 전체는 /common 엔티티에 부착된 SlayDeckController 단일 컴포넌트로 동작하며, 모든 산출물(ui/DefaultGroup.ui · SlayDeckController.codeblock · common.gamelogic)은 tools/deck/gen-slaydeck.mjs 단일 소스에서 생성됩니다(직접 편집 금지, 결정적 출력 — RULES.md 참조). 게임 데이터는 data/*.json 가 단일 소스.

구현된 기능 (배포 퀄리티 P1P12, PR #34#47)

영역	내용
캐릭터·전직	시작 시 전사(HP80)/마법사(HP70) 선택, 클래스별 시작 덱. 보스 클리어 시 [유물] vs [2차 전직] — 전사→파이터/페이지/스피어맨, 법사→위자드(불·독)/위자드(썬·콜)/클레릭. 전용 카드는 해당 클래스만 획득(보상·상점 풀 필터)
카드 전투	에너지 3·5장 드로우·드래그 사용(공격=적에 드롭, 스킬=위로 스윕). 카드 32종 — kind Attack/Skill/Power(파워: 소멸·매턴 지속 효과). 메커니즘: 다단히트·방어 무시·자가 디버프·드로·회복·전체 공격(AoE)·독(DoT)
버프/디버프	StS 표준 — 힘(+N 영구)·약화(주는 피해 −25%)·취약(받는 피해 +50%)·독(매 행동 틱). 양방향(적 디버프 인텐트 포함), 인텐트는 최종 예상치 표시
전투 연출	공격 이펙트·데미지 팝업·적 개별 차례·공격/피격/독뎀 모션(아바타 상태 전이·몬스터 hit 클립·런지/넉백)
절차 생성 맵	막 시작마다 8층×4열 StS식 경로 생성(런마다 다름). 층 규칙: 12층 전투만 → 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건

⚠️ 수치(적 스탯·경제·승천 배율)는 1차 조정 상태입니다. 정밀 밸런싱은 sim-balance.mjs로 검증하며 진행합니다.

유용한 스크립트 호출

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

local c = _EntityService:GetEntityByPath("/common").SlayDeckController
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. 상세 설계는 docs/slaymaple_basic_framework.md 및 docs/superpowers/specs/ 참조.

---

아키텍처 메모

현재 게임 전체 로직이 SlayDeckController 단일 codeblock에 모여 있습니다. 초기 설계 문서가 제안한 3분할(SlayCardCatalog/SlayRunState/SlayCombatManager)은 기능적으로 모두 구현됐으나 아직 한 컴포넌트 안에 있습니다. 시스템이 더 커지면 그때 분리를 고려합니다. 카드/적/맵/유물 데이터는 이미 data/*.json로 외부화돼 있습니다.

---

향후 개선 계획 (후속 후보)

• 전투 루프 · 런 루프 · 절차 생성 맵 · 상점/휴식/유물 방 · 유물 19종 · 물약 · 버프/디버프 · Power · 전직(전사/법사 2차) · 승천+개인 저장 · 전투 모션 (P1~P12 완료)
• 런 이어하기 — 진행 중 런 직렬화 저장(승천에서 도입한 UserDataStorage 확장, 메뉴의 "이어하기" 활성화)
• 카드 제거/업그레이드 — 상점 카드 제거 슬롯, 휴식 노드에서 카드 강화(StS 스타일 +수치)
• 이벤트 노드(?) — 랜덤 텍스트 이벤트(선택지·리스크/리워드)
• 3차 전직 — 2막 보스 보상으로 확장(크루세이더/나이트/버서커, 메이지 3차 등)
• 도적·궁수 클래스 — 캐릭터 선택 슬롯 확장(도적 잠금 해제), 클래스별 카드 풀
• 정밀 밸런싱 — 첫 인카운터 승률 100% 완화, 직업별 카드 효율 튜닝(sim-balance.mjs 리포트 기반)
• 상점 보장 규칙 — 막당 상점 최소 1회 등장(현재 가중 랜덤이라 미등장 가능)
• 연출 보강 — 사운드(타격·획득), EndTurn 버튼 적 턴 중 시각 비활성화, 맵 화면에 유물/물약 표시
• 승천 확장 — A10 초과 단계, 승천별 기록(클리어 횟수) 표시

---

신규 참여자 셋업

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
5. AI 에이전트(Claude Code 등)로 작업한다면 RULES.md 필독 — 생성 산출물 접근 금지(토큰 가드)·검증 절차·PR 도구(tools/git/gitea-pr.mjs) 규칙. Claude Code는 CLAUDE.md가 자동 적용